l10nUtil: add downloadTranslationFile and uploadTranslationFile commands to allow downloading and uploading from Crowdin.

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)