Add "UseSourceUsfm" option to USFM endpoint. (#420)

* Add "UseSourceUsfm" option to USFM endpoint. * Add template parameter when generating USFM --------- Co-authored-by: Damien Daspit <[email protected]>
sillsdev · Jul 5, 2024 · 8d24eff · 8d24eff
1 parent c149d4b
commit 8d24eff
Show file tree

Hide file tree

Showing 9 changed files with 427 additions and 215 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -26,6 +26,7 @@
     "Protobuf",
     "ptcc",
     "Rebinder",
+    "stylesheet",
     "upserted",
     "USFM"
   ],

diff --git a/src/Serval/src/Serval.Client/Client.g.cs b/src/Serval/src/Serval.Client/Client.g.cs
@@ -1627,25 +1627,27 @@ public partial interface ITranslationEnginesClient
         /// Get a pretranslated Scripture book in USFM format.
         /// </summary>
         /// <remarks>
-        /// If the USFM book exists in the target corpus, then the pretranslated text will be inserted into any empty
-        /// <br/>segments in the the target book and returned. If the USFM book does not exist in the target corpus, then the
-        /// <br/>pretranslated text will be inserted into an empty template created from the source USFM book and returned.
-        /// <br/>Only pretranslations for the most recent successful build of the engine are returned.
-        /// <br/>            
-        /// <br/>The text that populates the USFM structure can be controlled by the `textOrigin` parameter where with these options:
-        /// <br/>* `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text.  **This is the default**.
+        /// The text that populates the USFM structure can be controlled by the `textOrigin` parameter:
+        /// <br/>* `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text. **This is the default**.
         /// <br/>* `PreferPretranslated`: The existing and pretranslated texts are merged into the USFM, preferring pretranslated text.
-        /// <br/>* `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed)
-        /// <br/>* `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed
-        /// <br/>Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation)
+        /// <br/>* `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed).
+        /// <br/>* `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed.
+        /// <br/>            
+        /// <br/>The source or target book can be used as the USFM template for the pretranslated text. The template can be controlled by the `template` parameter:
+        /// <br/>* `Auto`: The target book is used as the template if it exists; otherwise, the source book is used. **This is the default**.
+        /// <br/>* `Source`: The source book is used as the template.
+        /// <br/>* `Target`: The target book is used as the template.
+        /// <br/>            
+        /// <br/>Only pretranslations for the most recent successful build of the engine are returned.
+        /// <br/>Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation).
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="corpusId">The corpus id</param>
         /// <param name="textId">The text id</param>
         /// <param name="textOrigin">The source[s] of the data to populate the USFM file with.</param>
         /// <returns>The book in USFM format</returns>
         /// <exception cref="ServalApiException">A server side error occurred.</exception>
-        System.Threading.Tasks.Task<string> GetPretranslatedUsfmAsync(string id, string corpusId, string textId, PretranslationUsfmTextOrigin? textOrigin = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
+        System.Threading.Tasks.Task<string> GetPretranslatedUsfmAsync(string id, string corpusId, string textId, PretranslationUsfmTextOrigin? textOrigin = null, PretranslationUsfmTemplate? template = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken));
 
         /// <param name="cancellationToken">A cancellation token that can be used by other objects or threads to receive notice of cancellation.</param>
         /// <summary>
@@ -3595,25 +3597,27 @@ public string BaseUrl
         /// Get a pretranslated Scripture book in USFM format.
         /// </summary>
         /// <remarks>
-        /// If the USFM book exists in the target corpus, then the pretranslated text will be inserted into any empty
-        /// <br/>segments in the the target book and returned. If the USFM book does not exist in the target corpus, then the
-        /// <br/>pretranslated text will be inserted into an empty template created from the source USFM book and returned.
-        /// <br/>Only pretranslations for the most recent successful build of the engine are returned.
-        /// <br/>            
-        /// <br/>The text that populates the USFM structure can be controlled by the `textOrigin` parameter where with these options:
-        /// <br/>* `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text.  **This is the default**.
+        /// The text that populates the USFM structure can be controlled by the `textOrigin` parameter:
+        /// <br/>* `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text. **This is the default**.
         /// <br/>* `PreferPretranslated`: The existing and pretranslated texts are merged into the USFM, preferring pretranslated text.
-        /// <br/>* `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed)
-        /// <br/>* `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed
-        /// <br/>Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation)
+        /// <br/>* `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed).
+        /// <br/>* `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed.
+        /// <br/>            
+        /// <br/>The source or target book can be used as the USFM template for the pretranslated text. The template can be controlled by the `template` parameter:
+        /// <br/>* `Auto`: The target book is used as the template if it exists; otherwise, the source book is used. **This is the default**.
+        /// <br/>* `Source`: The source book is used as the template.
+        /// <br/>* `Target`: The target book is used as the template.
+        /// <br/>            
+        /// <br/>Only pretranslations for the most recent successful build of the engine are returned.
+        /// <br/>Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation).
         /// </remarks>
         /// <param name="id">The translation engine id</param>
         /// <param name="corpusId">The corpus id</param>
         /// <param name="textId">The text id</param>
         /// <param name="textOrigin">The source[s] of the data to populate the USFM file with.</param>
         /// <returns>The book in USFM format</returns>
         /// <exception cref="ServalApiException">A server side error occurred.</exception>
-        public virtual async System.Threading.Tasks.Task<string> GetPretranslatedUsfmAsync(string id, string corpusId, string textId, PretranslationUsfmTextOrigin? textOrigin = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken))
+        public virtual async System.Threading.Tasks.Task<string> GetPretranslatedUsfmAsync(string id, string corpusId, string textId, PretranslationUsfmTextOrigin? textOrigin = null, PretranslationUsfmTemplate? template = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken))
         {
             if (id == null)
                 throw new System.ArgumentNullException("id");
@@ -3648,6 +3652,10 @@ public string BaseUrl
             {
                 urlBuilder_.Append(System.Uri.EscapeDataString("text-origin")).Append('=').Append(System.Uri.EscapeDataString(ConvertToString(textOrigin, System.Globalization.CultureInfo.InvariantCulture))).Append('&');
             }
+            if (template != null)
+            {
+                urlBuilder_.Append(System.Uri.EscapeDataString("template")).Append('=').Append(System.Uri.EscapeDataString(ConvertToString(template, System.Globalization.CultureInfo.InvariantCulture))).Append('&');
+            }
             urlBuilder_.Length--;
 
                     PrepareRequest(client_, request_, urlBuilder_);
@@ -6009,6 +6017,21 @@ public enum PretranslationUsfmTextOrigin
 
     }
 
+    [System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "14.0.2.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
+    public enum PretranslationUsfmTemplate
+    {
+
+        [System.Runtime.Serialization.EnumMember(Value = @"Auto")]
+        Auto = 0,
+
+        [System.Runtime.Serialization.EnumMember(Value = @"Source")]
+        Source = 1,
+
+        [System.Runtime.Serialization.EnumMember(Value = @"Target")]
+        Target = 2,
+
+    }
+
     [System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "14.0.2.0 (NJsonSchema v11.0.0.0 (Newtonsoft.Json v13.0.0.0))")]
     public partial class TranslationBuild
     {

diff --git a/src/Serval/src/Serval.Translation/Contracts/PretranslationUsfmTemplate.cs b/src/Serval/src/Serval.Translation/Contracts/PretranslationUsfmTemplate.cs
@@ -0,0 +1,8 @@
+namespace Serval.Translation.Contracts;
+
+public enum PretranslationUsfmTemplate
+{
+    Auto,
+    Source,
+    Target
+}
diff --git a/src/Serval/src/Serval.Translation/Controllers/TranslationEnginesController.cs b/src/Serval/src/Serval.Translation/Controllers/TranslationEnginesController.cs
@@ -617,17 +617,19 @@ CancellationToken cancellationToken
     /// Get a pretranslated Scripture book in USFM format.
     /// </summary>
     /// <remarks>
-    /// If the USFM book exists in the target corpus, then the pretranslated text will be inserted into any empty
-    /// segments in the the target book and returned. If the USFM book does not exist in the target corpus, then the
-    /// pretranslated text will be inserted into an empty template created from the source USFM book and returned.
-    /// Only pretranslations for the most recent successful build of the engine are returned.
-    ///
-    /// The text that populates the USFM structure can be controlled by the `textOrigin` parameter where with these options:
-    /// * `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text.  **This is the default**.
+    /// The text that populates the USFM structure can be controlled by the `textOrigin` parameter:
+    /// * `PreferExisting`: The existing and pretranslated texts are merged into the USFM, preferring existing text. **This is the default**.
     /// * `PreferPretranslated`: The existing and pretranslated texts are merged into the USFM, preferring pretranslated text.
-    /// * `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed)
-    /// * `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed
-    /// Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation)
+    /// * `OnlyExisting`: Return the existing target USFM file with no modifications (except updating the USFM id if needed).
+    /// * `OnlyPretranslated`: Only the pretranslated text is returned; all existing text in the target USFM is removed.
+    ///
+    /// The source or target book can be used as the USFM template for the pretranslated text. The template can be controlled by the `template` parameter:
+    /// * `Auto`: The target book is used as the template if it exists; otherwise, the source book is used. **This is the default**.
+    /// * `Source`: The source book is used as the template.
+    /// * `Target`: The target book is used as the template.
+    ///
+    /// Only pretranslations for the most recent successful build of the engine are returned.
+    /// Both scripture and non-scripture text in the USFM is parsed and grouped according to [this wiki](https://github.com/sillsdev/serval/wiki/USFM-Parsing-and-Translation).
     /// </remarks>
     /// <param name="id">The translation engine id</param>
     /// <param name="corpusId">The corpus id</param>
@@ -658,6 +660,7 @@ public async Task<IActionResult> GetPretranslatedUsfmAsync(
         [NotNull] string corpusId,
         [NotNull] string textId,
         [FromQuery(Name = "text-origin")] PretranslationUsfmTextOrigin? textOrigin,
+        [FromQuery] PretranslationUsfmTemplate? template,
         CancellationToken cancellationToken
     )
     {
@@ -674,6 +677,7 @@ CancellationToken cancellationToken
             corpusId,
             textId,
             textOrigin ?? PretranslationUsfmTextOrigin.PreferExisting,
+            template ?? PretranslationUsfmTemplate.Auto,
             cancellationToken
         );
         if (usfm == "")

diff --git a/src/Serval/src/Serval.Translation/Services/IPretranslationService.cs b/src/Serval/src/Serval.Translation/Services/IPretranslationService.cs
@@ -16,6 +16,7 @@ Task<string> GetUsfmAsync(
         string corpusId,
         string textId,
         PretranslationUsfmTextOrigin textOrigin,
+        PretranslationUsfmTemplate template,
         CancellationToken cancellationToken = default
     );
 }