Add instructions about translation workflow

[nvdaes]

Issue number

Fixes #2

Descriptions

This PR adds instructions about translating add-ons using the add-on template.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the submitter documentation to reflect that Crowdin-based translation support is now available via the NVDA Add-on Template, replacing outdated guidance.

Changes:

• Removes the statement that no recommended translation system is available.
• Updates wording to indicate Crowdin support is added to the Add-on Template.
• Adds a direct link to the template’s translation workflow documentation.

---

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

[nvdaes]

@seanbudd Feel free to review this when you can. This is ready.

[seanbudd]

Hmm - I tend to agree. I think we need a dedicated docs file / folder explaining 2 different things:

• how to set up syncing as an add-on author
• how to translate add-ons as a translator

[nvdaes]

@seanbudd wrote:

Hmm - I tend to agree. I think we need a dedicated docs file / folder explaining 2 different things:

OK, I'll add this in the next days, to be finished probably this weekend. I'm not a translator, so perhaps @abdel792, @CyrilleB79, @wmhn1872265132 and and others may want to review or comment on this.

[abdel792]

Hi @seanbudd and @nvdaes,

Following @seanbudd's suggestion, I wonder if it might be useful to create a dedicated translations documentation section rather than continuing to expand the submission guide.

Something like:

docs/
├── submitters/
│   └── submissionGuide.md
└── translations/
    ├── addOnAuthors.md
    └── translators.md

Where the two documents target different audiences.

addOnAuthors.md could explain:

• Creating or joining a Crowdin project.
• Configuring CROWDIN_TOKEN.
• Configuring CROWDIN_PROJECT_ID.
• Configuring MIN_PERCENTAGE_TRANSLATED.
• Setting up the AddonTemplate translation workflow.
• Documentation translation using XLIFF files.
• Translation synchronization between GitHub and Crowdin.
• Scheduled and manual workflow execution.

translators.md could explain:

• How to join a translation project.
• Translating add-ons in Crowdin.
• Translating documentation.
• The role of XLIFF files in documentation translation.
• How translations are synchronized back to GitHub.
• Who to contact when translation issues occur.
• Common questions and troubleshooting.

In that case, submissionGuide.md could simply contain a short introduction and links to the relevant translation documentation.

This might make the documentation easier to maintain and easier to navigate for both add-on authors and translators.

[abdel792]

As a follow-up to my previous comment, I have attached draft versions of:

• addOnAuthors.md
• translators.md

I have also included below a small proposal for updating the translation section of submissionGuide.md, so that it can serve as an entry point to the dedicated translation documentation.

@nvdaes, since you mentioned that you plan to work on this over the next few days, I thought these drafts might be useful as a starting point for your next commit on this PR.

Feel free to reuse, modify, reorganize, or discard any part of them if they are helpful.

My intention was mainly to provide a concrete example of how the documentation could be split between add-on authors/maintainers and translators, following @seanbudd's suggestion.

Proposed replacement for the current translation section in submissionGuide.md:

## Add-on translations

The NVDA Add-on Template includes built-in support for Crowdin-based translation workflows.

Translation support covers both user interface translations (`.po` files) and documentation translations (`.xliff` files).

Depending on your role, please refer to the appropriate documentation:

* Translation guide for add-on authors
* Translation guide for translators

These documents explain how translation synchronization works and how translations are contributed through Crowdin.

[nvdaes]

@abdel792 , thanks so much! I'm including your work in this PR (credits to you, of course, and I'll aknowledge it when this is announced on mailing lists).

[nvdaes]

@abdel792 , I've included your files with some modifications. In particular, I've removed the section about documentation for add-on authors, since there is not a section about interface. Also, I've added links and tried to highlight that the whole scripts folder should be used. Note that it contains languageMappings and setOutputs.py (used to store the add-on ID as an output in GitHub Actions, based on buildVars.py.

Also, note that GitHub Actions are using the nvdlUtil.exe file from nvaccess/nvdaL10n, which contains the configuration to use the NVDA add-ons Crowdin project. I think that we should mention that file instead of the l10nUtil.exe included in NVDA, but I'd like to request feedback by @seanbudd .

For me, this is ready for NV Access review, but I've converted the PR to draft in case you @abdel792 want to review it.
Thanks so much!

[abdel792]

@nvdaes, thank you very much for the review and for integrating my contributions.

I have looked through your latest changes and explanations, and everything looks good to me. Your adjustments make sense, especially the clarifications regarding the use of the whole scripts folder and the distinction between the nvdaL10n utility and the one distributed with NVDA.

I also agree that feedback from @seanbudd regarding the references to l10nUtil.exe would be useful before merging.

As far as I am concerned, I have nothing further to add at this stage. Thank you again for all the work you have put into this PR and for taking the time to refine and expand the documentation.

This looks ready for NV Access review from my side.

[seanbudd]

I think these files are better suited in the add-on template

[seanbudd]

Can you also reference the template files from NVDA in projectDocs\dev\addons.md and projectDocs\translating\readme.md? We can also update the link from https://github.com/nvaccess/nvda/wiki/TranslatingAddons

[nvdaes]

I've created nvaccess/AddonTemplate#36 PR, adding docs to the template.

Please note that credits about documentation should be given to @abdel792 .

About adding this to the NVDA repo, I can do it, but perhaps it would be better that this work is made by @abdel792 . Please Abdel, let me know how to proceed. I think you haven't contributed to the NVDA project, you are an efficient developer and you may want to start contributing.

[abdel792]

Hi @nvdaes,

Thanks for the kind words and for creating the AddonTemplate PR.

I would be happy to submit the documentation changes to the NVDA repository myself. This would actually be my first contribution to the official NVDA documentation, so it will be a new experience for me.

I'll try to work on it during the weekend and submit a PR updating projectDocs/dev/addons.md and projectDocs/translating/readme.md, including the updated template references.

Thanks again for the encouragement.

[nvdaes]

@abdel792 wrote:

I would be happy to submit the documentation changes to the NVDA repository myself.

Great! As you know, in projectDocs/dev/contributing.md, you can find guidance, and a section is dedicated for first contributors.
The documentation has been merged in the addonTemplate with small modifications.

[abdel792]

Thanks @nvdaes for the information and for pointing me to the contributor guide.

I'll take a look at projectDocs/dev/contributing.md, especially the section for first contributors.

I'm glad to hear that the documentation has been merged into the addonTemplate.

[CyrilleB79]

@abdel792 wrote:

I would be happy to submit the documentation changes to the NVDA repository myself. This would actually be my first contribution to the official NVDA documentation, so it will be a new experience for me.

First contribution to NVDA documentation but not first contribution to NVDA itself!
By the way, it's thanks to you Abdel that I did my first contribution to NVDA code many years ago! Thnings may have changed since then in the process. But you'll be able to go ahead with no problem. If you need help for something feel free to contact me, even in French. I won't be available this weekend though.

[abdel792]

Hi @seanbudd and @nvdaes,

I've just opened the PR:
nvaccess/nvda#20332

[abdel792]

Thanks @CyrilleB79!

You're right, I should have said my first contribution to the NVDA documentation. 😊

I had completely forgotten that I helped you with your first NVDA contribution. That's nice to hear! To me, it was only natural that we helped each other, as members of the NVDA community.

Thank you for the encouragement and for your offer to help. I really appreciate it, and I won't hesitate to ask you, even in French, if I need some guidance.

[nvdaes]

@seanbudd , I've fixed links (I realised that they were wrong thanks to PR opened by @abdel792 in NVDA project), and I think that this is ready for review.

[seanbudd]

can the added files be removed?

[nvdaes]

@seanbudd wrote:

can the added files be removed?

Done

[nvdaes]

Apologies, I had merged the master from my fork. Now all should be fixed.