Add scripts to allow addons from personal repos to be synchronized with Crowdin by nvdaes · Pull Request #1 · nvaccess/AddonTemplate

nvdaes · 2025-11-24T09:31:04Z

Blocked by #7

…th Crowdin

…rowdin ID

… addedwith dev role to Crowdin if they use a project not owned by them to upload source files)

…flow to upload/update files in Crowdin

…nements

…k pass creating a PR at nvdaes/translateNvdaaddonsWithCrowdin repo

seanbudd · 2025-11-27T00:52:53Z

 strictSetInference = true

 # Compliant rules
-reportAbstractUsage = true


it's probably better to keep these rules than dropping to NVDA's standard

nvdaes · 2025-11-28T06:24:33Z

Purpose

Add-on authors may wish to help translators use Crowdin, the same framework where they translate NVDA. to translate messages and documentation for maintained add-ons:

Other details

Pot file are created/updated, and uploaded to a Crowdin project.
The readme.md file is converted to xliff and uploaded to a Crowdin project.
Po and xfiles are translated.
Translated files are downloaded and processed to be copied to locale/langCode/LC_MESSAGES/nvda.po, and doc/langCode/readme.md, in the addon folder.
Authors need to store a Crowdin token with permissions to upload files to the Crowdin project as a repository secret.

Development approach

Use the Crowdin registration repo to add scripts usable by individual add-ons in personal repos.

nvdaes · 2025-11-28T06:28:43Z

I've tested that all check pass using this pyproject.toml file on this PR:

nvdaes/translateNvdaAddonsWithCrowdin#11

I use precommit, CodeQL and a workflow to check that all translatable messages have comments for translators.

I'll try to use the cache action to cache some add-on metadata like its id, and also hashfiles from l10nSources (taking the value of buildVars.py), and the hasf¡hfile of the readme.md, to determine if pot and xliff files should be updated.

nvdaes · 2025-11-30T17:19:32Z

Export translations to Crowdin running the workflow with update=False works properly:

https://github.com/nvdaes/translateNvdaAddonsWithCrowdin/actions/runs/19802210157

nvdaes · 2025-11-30T17:29:49Z

This time, updatexLiff is failing. Seems that adding blank lines to readme may cause problems:

https://github.com/nvdaes/translateNvdaAddonsWithCrowdin/actions/runs/19802391926/job/56731562709

nvdaes · 2025-11-30T19:29:23Z

If someone can help with this issue when update xliff, I'll be grateful.
I think that this is one of the bugest problems with xliff files. Sometimes sel lines are None and they don't have a strip method. I don't know if this should be also improved in NVDA
cc: @seanbudd

seanbudd · 2025-12-01T00:56:09Z

It might be easier to avoid xliff and just translate the markdown files directly. This won't support diffs very well but worth experimenting with

nvdaes · 2025-12-01T20:32:39Z

@seanbudd wrote:

It might be easier to avoid xliff and just translate the markdown files directly. This won't support diffs very well but worth experimenting with

OK.

nvdaes · 2025-12-03T18:03:39Z

@CyrilleB79, you were interested in this framework. If you want, feel free to see how the translateNvdaAddonsWithCrowdin.md can be translated in the project. Using xliff files is causing problems, as mentioned, and we are experimenting uploading md files instead.

nvdaes · 2026-04-08T04:33:26Z

@seanbudd wrote:

I think it's really important that the add-on dev community helps support this project.

I agree. Otherwise, we hav a lot of things to do in different projects. I'll request for volunteers for this. Good news is that I can print the list of members in the project via l10nUtil.exe.
If add-on devs don't support this, you may be still interested in adding this ability to nvdaL10n for managers.

- move Python helper scripts from .github/workflows to .github/scripts for better separation of concerns - add polib dependency and switch to uv sync for reproducible CI environment - fix missing GH_TOKEN required for GitHub CLI (gh) commands - fix l10nUtil.exe path resolution (use ./l10nUtil.exe instead of _l10n/l10nUtil.exe) - improve Crowdin download behavior by avoiding processing empty translation files - refine PO handling: preserve local translations, conditionally upload to Crowdin when needed - refine XLIFF handling: update local documentation only, no upload back to Crowdin - ensure safer, more deterministic, and more predictable translation synchronization logic

The script is already available in .github/scripts/.

Improve crowdinL10n.yml translation workflow

nvdaes · 2026-04-20T16:48:49Z

pre-commit.ci run

nvdaes · 2026-04-20T17:29:06Z

Thanks @abdel792 for contributing this PR via nvdaes#2

I've run pre-commit, and I think that this needs to be cleaned. For example, since we are using l10nUtil.exe, we may remove some dependencies.
I'll work on this. Let me know if something is missing from my side.

… master branch

nvdaes · 2026-04-22T17:59:26Z

@seanbudd , I think this is ready for review. The workflow implemented by @abdel792 works well, though seems that xliff files may not work well for old add-ons, probably due to extra spaces in markdown files. We used a readme.md, and then we had to copy it to the svn repo with some modifications. I guess that something may be broken in the conversion or in the format, not sure.
@abdel792 , can you share a workflow to demonstrate how xliff files are transformed to md in the l10n branch of personal repos please?
I can show this successful workflow:

https://github.com/nvdaes/readFeeds/actions/runs/24792870808/job/72554821619

Also, I think that we will need to create a different PR to document how to upload pot and xliff files, including updating them if the markdown file is updated.

…on logic - Add Markdown language scoring (langid) in checkTranslation.py - Extend script to support MD files and optional multi-file comparison - Update workflow to handle XLIFF → MD conversion only when translated - Implement multi-source comparison (XLIFF MD, remote MD, local MD) - Apply best-quality selection before updating or uploading files - Add full logging for all decision branches - Improve fallback behavior when only one source is available

Improve Crowdin localization workflow with intelligent MD/XLIFF handling

nvdaes · 2026-04-23T00:00:38Z

@seanbudd, @abdel792 has made more and significant improvements. This can be shown here

https://github.com/nvdaes/readFeeds/actions/runs/24808570637/job/72608265836

I'll resolve conflicts and mark this as ready for review again.

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-23T06:33:52Z

+	addonId = buildVars.addon_info["addon_name"]
+	name = "addonId"
+	value = addonId
+	with open(os.environ["GITHUB_OUTPUT"], "a") as f:


GITHUB_OUTPUT is accessed unconditionally; if this script is run outside GitHub Actions (or the env var is missing), it will raise a KeyError with a confusing traceback. Consider validating os.environ.get("GITHUB_OUTPUT") and exiting with a clear error message when it’s not set.

Suggested change

with open(os.environ["GITHUB_OUTPUT"], "a") as f:

githubOutput = os.environ.get("GITHUB_OUTPUT")

if not githubOutput:

print(

"Error: GITHUB_OUTPUT is not set. This script must be run in a GitHub Actions step "

"with GITHUB_OUTPUT available.",

file=sys.stderr,

)

raise SystemExit(1)

with open(githubOutput, "a") as f:

This will be run inside GitHub Actions.

Copilot · 2026-04-23T06:33:52Z

+Then, to export your add-on to Crowdin for the first time, run the `.github/workflows/exportAddonsToCrowdin.yml`, ensuring that the update option is set to false.
+When you have updated messages or documentation, run the workflow setting update to true (which is the default option).


The workflow referenced here (.github/workflows/exportAddonsToCrowdin.yml) doesn’t exist in this PR; the added workflow is crowdinL10n.yml. Please update the documentation to reference the correct workflow name (and ensure the described inputs/options like update=false match what the workflow actually supports).

I'll update the readme

Copilot · 2026-04-23T06:33:52Z

+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync


uv sync will re-resolve dependencies if no lockfile is present, which can make CI non-reproducible (and slower). If the intent is to use locked deps, re-add uv.lock to the repo and run uv sync --frozen/--locked (or equivalent) so this workflow fails if the lock is out of date.

Suggested change

run: uv sync

run: uv sync --locked

lock file should be present

Copilot · 2026-04-23T06:33:53Z

+              if ($xliffValid) {
+                Write-Host "Converting XLIFF → MD"
+                $tempMd = "$env:TEMP\readme_$langCode.md"
+                ./l10nUtil.exe xliff2md $xliffFile $tempMd


After running l10nUtil.exe xliff2md, the script assumes $tempMd was created and later Move-Items it. If xliff2md fails (non-zero exit code or no output file), this can cause misleading behavior or runtime errors. Consider checking $LASTEXITCODE and Test-Path $tempMd before proceeding, and fail the step when conversion fails.

Suggested change

./l10nUtil.exe xliff2md $xliffFile $tempMd

./l10nUtil.exe xliff2md $xliffFile $tempMd

if ($LASTEXITCODE -ne 0 -or -not (Test-Path $tempMd)) {

throw "xliff2md failed for '$xliffFile' or did not create expected output '$tempMd'."

}

I think this is not needed for this workflow.

Copilot · 2026-04-23T06:33:53Z

+      - name: Download l10nUtil
+        run: |
+          gh release download --repo nvaccess/nvdaL10n --pattern "l10nUtil.exe"
+
+      - name: Download translations from Crowdin
+        shell: pwsh
+        run: |
+          ./l10nUtil.exe exportTranslations -o _addonL10n -c addon
+


This step runs several external commands (gh release download, l10nUtil.exe exportTranslations, l10nUtil.exe uploadTranslationFile, etc.) but doesn’t enforce failure on non-zero exit codes. In PowerShell, most external-command failures won’t stop the script unless you check $LASTEXITCODE (or explicitly throw/exit). Recommend adding strict error handling so the workflow fails fast when downloads/exports/uploads fail.

Copilot · 2026-04-23T06:33:53Z

+
+            git switch ${{ env.downloadTranslationsBranch }} 2>$null
+            if ($LASTEXITCODE -ne 0) {
+              git switch -c ${{ env.downloadTranslationsBranch }}
+            }
+
+            git push -f --set-upstream origin ${{ env.downloadTranslationsBranch }}


The workflow commits on the current branch, then switches/creates the l10n branch afterwards. If l10n already exists locally, git switch l10n will move HEAD away from the new commit and the subsequent push won’t include the translation update. Switch/create/reset the target branch before committing (or explicitly push the commit to l10n, e.g. git push origin HEAD:l10n).

Suggested change

git switch ${{ env.downloadTranslationsBranch }} 2>$null

if ($LASTEXITCODE -ne 0) {

git switch -c ${{ env.downloadTranslationsBranch }}

}

git push -f --set-upstream origin ${{ env.downloadTranslationsBranch }}

git push -f --set-upstream origin HEAD:${{ env.downloadTranslationsBranch }}

l10n shouldn't exis locally since the main branch will be checked out.

nvdaes added 9 commits November 24, 2025 10:24

Add scripts to allow addons from personal repos to be synchronized wi…

28c060d

…th Crowdin

use a json file to store addonId, and use it to filter files to get C…

4669430

…rowdin ID

Try to get files just for the current add-on

b188560

Add workflow to export an add-on to Crowdin (authors would need to be…

7092615

… addedwith dev role to Crowdin if they use a project not owned by them to upload source files)

Use buildVars, not metadata.json file

e89640d

Add userAccount to buildVars, and step to get addon-id to GitHub work…

4c7771b

…flow to upload/update files in Crowdin

Update files after testing exporting an add-on to Crowdin, needs refi…

c529cee

…nements

Add python version file

186b755

Improve pyproject and update precommit config after testing that chec…

f1fbf8e

…k pass creating a PR at nvdaes/translateNvdaaddonsWithCrowdin repo

seanbudd reviewed Nov 27, 2025

View reviewed changes

nvdaes added 4 commits November 27, 2025 07:05

Restore rules

b867a9a

Restore pyproject

47ed91c

Improve uv project

402002e

Remove files

d820711

nvdaes added 3 commits November 29, 2025 17:41

Calculate hash of i18nSources

9f6b3dc

Update workflow

4c938ec

Update _l10n

a303210

Upload md file

a0d02da

Updates

a8d4252

nvdaes added 3 commits December 14, 2025 13:19

Update l10nUtil

1a1e6fd

Update workflow

d2395b0

Update readme

e4dafe1

nvdaes and others added 7 commits April 18, 2026 07:04

Improve workflow to download files from Crowdin

e699abc

Update setOutputs to set just add-on id to download translations

5eafa64

Remove duplicate setOutputs.py from .github/workflows

a195110

The script is already available in .github/scripts/.

Merge pull request #2 from abdel792/l10nImprovements

9ed44a3

Improve crowdinL10n.yml translation workflow

Update lock

e62bd5b

Merge

37c4d4f

Try to fix pre-commit configuration

91995bd

nvdaes added 7 commits April 20, 2026 19:53

Reset gitignore to master

0c613be

Require polib 1.2.0

0b65072

Update lock file

f9ba8fe

Remove sha256 file

8e514ba

Remove verification of lock file in pre-commit config, not present in…

9c64247

… master branch

Remove Crowdin client

7589fef

Update lock file

94b1a88

nvdaes marked this pull request as ready for review April 22, 2026 17:55

abdel792 and others added 3 commits April 23, 2026 00:27

Merge pull request #3 from abdel792/l10nImprovements

059bb53

Improve Crowdin localization workflow with intelligent MD/XLIFF handling

Run pre-commit

c9c3bab

nvdaes marked this pull request as draft April 22, 2026 23:59

Fix conflicts

25dcb5d

nvdaes marked this pull request as ready for review April 23, 2026 00:09

seanbudd requested a review from Copilot April 23, 2026 06:29

Copilot started reviewing on behalf of seanbudd April 23, 2026 06:30 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

-	with open(os.environ["GITHUB_OUTPUT"], "a") as f:
+	githubOutput = os.environ.get("GITHUB_OUTPUT")
+	if not githubOutput:
+		print(
+			"Error: GITHUB_OUTPUT is not set. This script must be run in a GitHub Actions step "
+			"with GITHUB_OUTPUT available.",
+			file=sys.stderr,
+		)
+		raise SystemExit(1)
+	with open(githubOutput, "a") as f:

		Then, to export your add-on to Crowdin for the first time, run the `.github/workflows/exportAddonsToCrowdin.yml`, ensuring that the update option is set to false.
		When you have updated messages or documentation, run the workflow setting update to true (which is the default option).

Conversation

nvdaes commented Nov 24, 2025 • edited by seanbudd Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

seanbudd Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

nvdaes commented Nov 28, 2025

Purpose

Other details

Development approach

Uh oh!

nvdaes commented Nov 28, 2025

Uh oh!

nvdaes commented Nov 30, 2025

Uh oh!

nvdaes commented Nov 30, 2025

Uh oh!

nvdaes commented Nov 30, 2025

Uh oh!

seanbudd commented Dec 1, 2025

Uh oh!

nvdaes commented Dec 1, 2025

Uh oh!

nvdaes commented Dec 3, 2025

Uh oh!

nvdaes commented Apr 8, 2026

Uh oh!

nvdaes commented Apr 20, 2026

Uh oh!

nvdaes commented Apr 20, 2026

Uh oh!

nvdaes commented Apr 22, 2026

Uh oh!

nvdaes commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

nvdaes Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

nvdaes Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

nvdaes Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

nvdaes Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

nvdaes Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

nvdaes commented Nov 24, 2025 •

edited by seanbudd

Loading