diff --git a/docs/l10n/addonAuthors.md b/docs/l10n/addonAuthors.md new file mode 100644 index 0000000..5fa5831 --- /dev/null +++ b/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. diff --git a/docs/l10n/addonTranslators.md b/docs/l10n/addonTranslators.md new file mode 100644 index 0000000..209a144 --- /dev/null +++ b/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. diff --git a/readme.md b/readme.md index 8967772..3d80f87 100644 --- a/readme.md +++ b/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