Add documentation about add-on translation

docs/l10n/addonAuthors.md

@@ -0,0 +1,61 @@
+# Translation Guide for Authors
+
+## Overview
+
+This template supports translating add-ons with Crowdin.
+
+## Crowdin Project Setup
+
+You need a Crowdin account and an API token with permissions to manage a project.
+If you wish to use the community project [Crowdin project to translate NVDA add-ons](https://crowdin.com/project/nvdaaddons):
+
+* **Request Access:** Send a message to the [NVDA translation mailing list](https://groups.io/g/nvda-translations) (**nvda-translations@groups.io**), or in the [NVDA Add-ons Mailing List](https://groups.io/g/nvda-addons) (**nvda-addons@groups.io**), requesting an invitation to join the project as a developer.
+* **API Token:** Once invited, generate an API token in your Crowdin account settings.
+
+## GitHub Secrets and Variables
+
+To allow the workflows to communicate with Crowdin, you must add the following secret to your GitHub repository (`Settings > Secrets and variables > Actions`):
+
+* `CROWDIN_TOKEN`: Paste your Crowdin API token here.
+
+Optionally, if you don't want to use the [Crowdin community project](https://crowdin.com/project/nvdaaddons), you can create repository variables from **Settings > Secrets and variables > Actions > Variables** by selecting the **Variables** tab and clicking **New repository variable**.
+
+The following repository variables are supported:
+
+* `CROWDIN_PROJECT_ID`: Paste the project ID of your Crowdin project.
+* `L10N_UTIL_CONFIG`: The path to the YAML file containing the configuration for `l10nUtil.exe`, used by the translation scripts.
+For more details, visit the [nvdaL10n repository](https://github.com/nvaccess/nvdaL10n).
+* `MIN_PERCENTAGE_TRANSLATED`: Defines the minimum translation completion percentage required before a translated file is synchronized back to the repository.
+The value must be between `0` and `100`.
+
+Examples for `MIN_PERCENTAGE_TRANSLATED`:
+
+* `50`: Import files that are at least 50% translated.
+* `75`: Import files that are at least 75% translated.
+* `100`: Import only fully translated files.
+
+If `MIN_PERCENTAGE_TRANSLATED` is not defined, the workflow uses a default value of `50`.
+
+## Infrastructure
+
+Ensure that your repository includes the following files (provided in this template):
+
+* **Workflows:** `.github/workflows/crowdinL10n.yml`
+* **Scripts:** The `.github/scripts/` folder containing `checkTranslation.py`, `languageMappings.json`, `setOutputs.py`, and `crowdinSync.ps1`.
+
+Documentation synchronization relies on the XLIFF support built into `l10nUtil.exe`.
+
+The `md2xliff` command is used to generate the source XLIFF file from the English `readme.md` documentation file.
+Translated XLIFF files downloaded from Crowdin are then converted back to Markdown documentation using `l10nUtil.exe xliff2md`.
+
+## Running the Workflow
+
+The translation workflow will be run weekly.
+Also, you can run the workflow manually from GitHub or using GitHub CLI.
+
+If you manage several add-ons, consider using different cron schedules for each repository.
+Although the workflow includes a random startup delay to reduce collisions, concurrent Crowdin synchronization jobs may still occur.
+
+Documentation and interface translations are synchronized only when their translation percentage reaches the configured `MIN_PERCENTAGE_TRANSLATED` threshold.
+
+This validation mechanism is applied consistently to both `.po` and `.xliff` translation files.

docs/l10n/addonTranslators.md

@@ -0,0 +1,219 @@
+# Translation Guide for Translators
+
+## Overview
+
+Many NVDA add-ons use the NVDA Add-ons Crowdin project (`nvdaaddons`) to manage translations.
+
+This project allows translators to contribute both interface translations and documentation translations.
+
+Translations are synchronized back to add-on repositories through the localization workflow provided by the NVDA Add-on Template.
+
+## Joining the Translation Community
+
+Before contributing translations, translators are encouraged to subscribe to the NVDA Translations mailing list.
+
+The mailing list is the primary place for discussing translation-related topics within the NVDA community.
+
+## NVDA Translations Mailing List
+
+The NVDA community maintains the NVDA Translations mailing list on Groups.io.
+
+This mailing list is used to:
+
+* Discuss translation-related topics.
+* Request access to translation teams.
+* Coordinate translation efforts.
+* Report translation issues.
+* Discuss problems affecting translation tools or workflows.
+
+Translators are encouraged to subscribe to the mailing list:
+
+https://groups.io/g/nvda-translations
+
+The mailing list is often the best place to ask questions, request access to a translation team, and seek assistance from other translators and project maintainers.
+
+## Joining the Translation Project
+
+To contribute translations:
+
+1. Create a Crowdin account.
+1. Subscribe to the NVDA Translations mailing list.
+1. Request access to the appropriate translation team if necessary.
+1. Join the NVDA Add-ons Crowdin project.
+1. Select the language you wish to translate.
+1. Begin translating interface strings and documentation.
+
+## Translation Methods
+
+Translations can be performed using either the Crowdin web interface or local translation tools.
+
+### Crowdin Web Editor
+
+Crowdin provides a web-based editor that allows translators to:
+
+* Translate strings online.
+* Review existing translations.
+* Suggest improvements.
+* Vote on translation proposals.
+
+This method does not require any additional software installation.
+
+### Poedit
+
+Many NVDA translators prefer to work locally using [Poedit](https://poedit.com/) because of its accessibility and ease of use.
+
+Poedit supports both:
+
+* Portable Object (`.po`) files used for interface translations.
+* XLIFF (`.xliff`) files used for documentation translations.
+
+After completing translations locally, files can be uploaded back to Crowdin using [l10nUtil.exe](https://github.com/nvaccess/nvdaL10n/releases/latest).
+
+## Translating Interface Strings
+
+Interface translations are stored in Portable Object (`.po`) files.
+
+These files can be translated either:
+
+* Directly in Crowdin.
+* Using Poedit.
+
+## Translating Documentation
+
+Documentation translations are stored in XLIFF (`.xliff`) files.
+
+These files are generated automatically from the add-on documentation.
+
+Documentation can be translated:
+
+* Directly in Crowdin.
+* Using Poedit.
+
+When translating documentation:
+
+* Translate only the text content.
+* Preserve placeholders and formatting.
+* Do not modify the XLIFF structure manually.
+
+## Uploading Offline Translations
+
+After translating files locally, they can be uploaded to Crowdin using [l10nUtil.exe](https://github.com/nvaccess/nvdaL10n/releases/latest)
+
+Examples:
+
+```cmd
+l10nUtil.exe uploadTranslationFile fr addonName.po -c addon
+```
+
+```cmd
+l10nUtil.exe uploadTranslationFile fr addonName.xliff -c addon
+```
+
+Where:
+
+* `fr` is the Crowdin language code.
+* `addonName.po` is a translated interface file.
+* `addonName.xliff` is a translated documentation file.
+
+Once uploaded, the translations become available in Crowdin and can later be synchronized back into the add-on repository.
+
+## Using l10nUtil.exe
+
+To display the complete list of available commands:
+
+```cmd
+l10nUtil.exe --help
+```
+
+or:
+
+```cmd
+l10nUtil.exe -h
+```
+
+To display help for a specific command:
+
+```cmd
+l10nUtil.exe downloadTranslationFile --help
+```
+
+or:
+
+```cmd
+l10nUtil.exe downloadTranslationFile -h
+```
+
+Refer to the utility help output for a complete list of supported commands and options.
+
+## How Synchronization Works
+
+Translations are not immediately imported into GitHub repositories.
+
+The add-on maintainer runs a synchronization workflow that:
+
+1. Connects to the NVDA Add-ons Crowdin project.
+1. Downloads completed translations.
+1. Verifies their translation completion percentage.
+1. Synchronizes eligible translations back into the repository.
+
+Depending on the repository configuration, translations may only be synchronized after reaching a minimum completion percentage.
+
+This threshold is controlled by the add-on maintainer.
+
+## Why Has My Translation Not Appeared Yet?
+
+Possible reasons include:
+
+* The synchronization workflow has not yet run.
+* The required translation completion percentage has not yet been reached.
+* The maintainer has temporarily disabled synchronization.
+* The translation was completed after the most recent synchronization cycle.
+
+## Best Practices
+
+To improve translation quality:
+
+* Maintain consistency with existing terminology.
+* Preserve placeholders and formatting.
+* Review existing translations before introducing new terminology.
+* Coordinate with other translators whenever possible.
+* Test translated files locally before uploading them when possible.
+
+## Reporting Problems
+
+If you encounter translation issues:
+
+* Contact the add-on maintainer.
+* Open an issue in the add-on repository if appropriate.
+* Ask for assistance on the NVDA Translations mailing list.
+* Discuss translation-related issues with the NVDA translation community.
+
+## Frequently Asked Questions
+
+### Can I translate both documentation and interface strings?
+
+Yes.
+
+The NVDA Add-ons Crowdin project supports both interface translations (`.po`) and documentation translations (`.xliff`).
+
+### Do I need to use the Crowdin web interface?
+
+No.
+
+Many translators work directly in Crowdin, while others prefer to use Poedit and upload their completed translations afterwards using `l10nUtil.exe`.
+
+Both approaches are supported by the NVDA Add-ons translation workflow.
+
+### Do I need access to GitHub?
+
+Not necessarily.
+
+Most translators work exclusively through Crowdin or through local translation tools combined with `l10nUtil.exe`.
+
+The synchronization workflow is managed by the add-on maintainer and automatically imports translations into GitHub repositories.
+
+### Can I force synchronization?
+
+No.
+
+Synchronization is controlled by the add-on maintainer through the localization workflow provided by the NVDA Add-on Template.

readme.md

@@ -182,72 +182,9 @@ If not, leave the dictionary empty.
 
 This template allows you to automate the synchronization of documentation and interface messages with Crowdin.
 
-#### Documentation Translation Format
+For more details, please see the [translation guide for add-on authors](./docs/l10n/addonAuthors.md).
 
-Documentation translations are managed through XLIFF files in Crowdin.
-
-The synchronization workflow generates an XLIFF source file from the English `readme.md` documentation using `l10nUtil.exe md2xliff`.
-
-Translators work on the XLIFF file in Crowdin.
-During synchronization, translated XLIFF files are downloaded and converted back to Markdown using `l10nUtil.exe xliff2md`.
-
-XLIFF is considered the single source of truth for documentation translations.
-Legacy Markdown translation files may still exist on Crowdin, but they are ignored by the synchronization workflow.
-
-#### 1. Crowdin Project Setup
-
-You need a Crowdin account and an API token with permissions to manage a project.
-If you wish to use the community project [Crowdin project to translate NVDA add-ons](https://crowdin.com/project/nvdaaddons):
-
-* **Request Access:** Send a message to the [NVDA translation mailing list](https://groups.io/g/nvda-translations) (**nvda-translations@groups.io**), or in the [NVDA Add-ons Mailing List](https://groups.io/g/nvda-addons) (**nvda-addons@groups.io**), requesting an invitation to join the project as a developer.
-* **API Token:** Once invited, generate an API token in your Crowdin account settings.
-
-#### 2. GitHub Secrets and Variables
-
-To allow the workflows to communicate with Crowdin, you must add the following secret to your GitHub repository (`Settings > Secrets and variables > Actions`):
-
-* `CROWDIN_TOKEN`: Paste your Crowdin API token here.
-
-Optionally, if you don't want to use the [Crowdin community project](https://crowdin.com/project/nvdaaddons), you can create repository variables from **Settings > Secrets and variables > Actions > Variables** by selecting the **Variables** tab and clicking **New repository variable**.
-
-The following repository variables are supported:
-
-* `CROWDIN_PROJECT_ID`: Paste the project ID of your Crowdin project.
-* `L10N_UTIL_CONFIG`: The path to the YAML file containing the configuration for `l10nUtil.exe`, used by the translation scripts.
-For more details, visit the [nvdaL10n repository](https://github.com/nvaccess/nvdaL10n).
-* `MIN_PERCENTAGE_TRANSLATED`: Defines the minimum translation completion percentage required before a translated file is synchronized back to the repository.
-The value must be between `0` and `100`.
-
-Examples for `MIN_PERCENTAGE_TRANSLATED`:
-
-* `50`: Import files that are at least 50% translated.
-* `75`: Import files that are at least 75% translated.
-* `100`: Import only fully translated files.
-
-If `MIN_PERCENTAGE_TRANSLATED` is not defined, the workflow uses a default value of `50`.
-
-#### 3. Infrastructure
-
-Ensure that your repository includes the following files (provided in this template):
-
-* **Workflows:** `.github/workflows/crowdinL10n.yml`
-* **Scripts:** The `.github/scripts/` folder containing `checkTranslation.py`, `languageMappings.json`, `setOutputs.py`, and `crowdinSync.ps1`.
-
-Documentation synchronization relies on the XLIFF support built into `l10nUtil.exe`.
-
-The `md2xliff` command is used to generate the source XLIFF file from the English `readme.md` documentation file.
-Translated XLIFF files downloaded from Crowdin are then converted back to Markdown documentation using `l10nUtil.exe xliff2md`.
-
-#### 4. Running the Workflow
-
-The translation workflow will be run weekly.
-Also, you can run the workflow manually from GitHub or using GitHub CLI.
-
-If you manage several add-ons, consider using different cron schedules for each repository. Although the workflow includes a random startup delay to reduce collisions, concurrent Crowdin synchronization jobs may still occur.
-
-Documentation and interface translations are synchronized only when their translation percentage reaches the configured `MIN_PERCENTAGE_TRANSLATED` threshold.
-
-This validation mechanism is applied consistently to both `.po` and `.xliff` translation files.
+A [translation guide for translators](./docs/l10n/addonTranslators.md) is also available.
 
 ### Additional tools