l10nUtil: add downloadTranslationFile and uploadTranslationFile comma…

…nds to allow downloading and uploading from Crowdin. (#17708)

Currently, a translator must manually download and upload files from Crowdin. This can take time and is easy to use the wrong settings when importing and exporting.

Description of user facing changes
A translator can now download a file using the NVDA l10nUtil:

l10nUtil downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
E.g.

l10nUtil downloadTranslationFile fr userguide.xliff
This will download the file, and preprocess it, avoiding bugs in the Crowdin exporter, including filtering of corrupt target strings.
The translator can then translate the file with Poedit as normal.
The translator can now upload the file back to Crowdin using the NVDA l10nUtil:

l10nUtil uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>] [--old <oldLocalFilePath>] 
E.g.

l10nUtil uploadTranslationFile fr userguide.xliff --old userguide_old.xliff
The --old argument allows you to provide the original downloaded file before it was last translated with Poedit, so that only added / changed translations are uploaded to Crowdin, decreasing the possibility of overriding someone elses work on this language.

Note that the download and upload commands of l10nUtil require a Crowdin auth token. The first time, the token will be asked for. You will need to create a personal access token in your Crowdin settings, ensuring it has the Translations scope at a minimum.
Paste this token into the user prompt. l10nUtil will save this in `/.nvda_crowdin for future use.

Description of development approach
l10nutil.py has new commands that use the Crowdin API.

projectDocs/translating/crowdin.md

@@ -64,9 +64,28 @@ Some comments provide an example output message to help you understand what NVDA
 
 ## Translating NVDA's interface
 
-* Download nvda.po from the Files section of your language on Crowdin.
-* Open the po file in Poedit, translate, and save the file.
-* Upload the po file back to Crowdin.
+* Download the po file for your language from  Crowdin using NVA's l10nUtil.exe:
+```
+l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+```
+E.g.
+```
+l10nUtil.exe downloadTranslationFile fr nvda.po
+```
+The first time you will be asked for an authorization token.
+Please visit [your Crowdin settings API page](https://crowdin.com/settings#api-key) and create a Personal Access Token.
+Ensure that it has at least the translations scope.
+Then paste this into the user prompt.
+This will be saved in ~/.nvda_crowdin for future use.
+* Open the xliff file in Poedit, translate, and save the file.
+* Upload the translated file using l10nUtil
+```
+l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+```
+E.g.
+```
+l10nUtil.exe uploadTranslationFile fr nvda.po
+```
 
 Alternatively, you can use the [Crowdin interface directly](https://support.crowdin.com/online-editor/).
 
@@ -163,15 +182,30 @@ Documentation available for translation includes:
 
 To translate any of these files:
 
-* Download the xliff file from the Files section of your language on Crowdin.
-    * Make sure to choose "Download" not "Export xliff".
-* Make a copy of this file.
+* Download the xliff file for your language from  Crowdin using NVA's l10nUtil.exe:
+```
+l10nUtil.exe downloadTranslationFile <language> <crowdinFilePath> [<localFilePath>]
+```
+E.g.
+```
+l10nUtil.exe downloadTranslationFile fr userGuide.xliff
+```
+The first time you will be asked for an authorization token.
+Please visit [your Crowdin settings API page](https://crowdin.com/settings#api-key) and create a Personal Access Token.
+Ensure that it has at least the translations scope.
+Then paste this into the user prompt.
+This will be saved in ~/.nvda_crowdin for future use.
+* Make a copy of the downloaded file.
 * Open the xliff file in Poedit, translate, and save the file.
-* Use the NVDA l10nUtil program to strip the xliff so that it only contains translations that were added / changed. E.g.
+* Upload the translated file using l10nUtil
+```
+l10nUtil.exe uploadTranslationFile <language> <crowdinFilePath> [<localFilePath>] [--old <oldLocalFilepath>]
+```
+E.g.
 ```
-l10nUtil.exe stripXliff -o <old xliff file> <translated xliff file> <output stripped xliff file>
+l10nUtil.exe uploadTranslationFile fr userGuide.xliff --old userGuide_backup.xliff
 ```
-* Upload the xliff file back to Crowdin. If it is a stripped xliff file, it is safe to check the `allow target to match source` checkbox.
+This will only upload added / changed translations since you downloaded the file.
 
 Alternatively, you can use the [Crowdin interface directly](https://support.crowdin.com/online-editor/).
 

requirements.txt

@@ -24,6 +24,8 @@ pycaw==20240210
 py2exe==0.13.0.2
 # xliff2html is packaged with nuitka 
 nuitka==2.5.4
+# l10nUtil requires Crowdin 
+crowdin-api-client==1.21.0
 
 # Creating XML unit test reports
 unittest-xml-reporting==3.2.0

sconstruct

@@ -734,8 +734,8 @@ env.Alias("moduleList", env.GenerateModuleList(target, source))
 
 nvdaL10nUtil = env.Command(
 	target=outputDir.File("l10nUtil.exe"),
-	source="user_docs/l10nUtil.py",
+	source="user_docs\l10nUtil.py",
 	ENV=os.environ,
-	action=f"nuitka --assume-yes-for-downloads --remove-output --standalone --onefile --output-dir={outputDir.abspath} --include-module=mdx_truly_sane_lists --include-module=markdown_link_attr_modifier --include-module=mdx_gh_links user_docs/l10nUtil.py",
+	action=f"nuitka --assume-yes-for-downloads --remove-output --standalone --onefile --output-dir={outputDir.abspath} --include-module=mdx_truly_sane_lists --include-module=markdown_link_attr_modifier --include-module=mdx_gh_links $SOURCE",
 )
 env.Alias("nvdaL10nUtil", nvdaL10nUtil)