Add a dedicated translator guide document #1494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Merged

per1234 merged 2 commits into arduino:main from per1234:translation-guide

Sep 26, 2022

Merged

Add a dedicated translator guide document #1494

per1234 merged 2 commits into arduino:main from per1234:translation-guide

Sep 26, 2022

Conversation

per1234

Copy link

Contributor

@per1234 per1234 commented Sep 25, 2022

Motivation

Translation of the strings of the Arduino IDE UI is a valuable contribution which helps to make Arduino accessible to everyone around the world.

Localization of the Arduino-specific strings of the IDE is done in the "Arduino IDE 2.0" project on Transifex. Previously, the "Translation" row in the contribution methods summary table in the contributor guide entry page simply linked to that project.

Arduino IDE also uses localized strings from several other sources:

Users may notice unlocalized strings or errors or areas for improvement in the existing translations and wish to contribute translations. For this reason, it is important to also provide instructions for contributing to those other localization data sources.

Change description

Creation of translator guide document

The contribution methods summary table can not effectively accommodate the additional content required to document all localization data sources so addition of a dedicated document is proposed for the purpose.

The use of a dedicated document for this information will also allow linking directly to that information from related documentation or conversations.

Add readme for localization data

Experience with maintenance of Arduino's localized projects indicates that the localization data files can appear to be the appropriate place to make edits for casual contributors not familiar with the project's sophisticated internationalization infrastructure.

Examples:

Since those files are generated by automated systems, any edits made there would only be overwritten, so it is important to clearly communicate the correct way to make enhancements or corrections to these strings. This is accomplished by a local readme file most likely to be seen by those working in the folder containing these files. This file supplements the existing information about translation in the project's translation guide.

Other information

The rendered documents can be previewed here:

https://github.com/per1234/arduino-ide/blob/translation-guide/docs/contributor-guide/translation.md

https://github.com/per1234/arduino-ide/tree/translation-guide/i18n#readme

Reviewer checklist

PR addresses a single concern.
The PR has no duplicates (please search among the Pull Requests before creating one)
PR title and description are properly filled.
Docs have been added / updated (for bug fixes / features)

@per1234 per1234 added topic: documentation type: enhancement labels

Sep 25, 2022

@per1234 per1234 requested review from kittaakos, AlbyIanna and francescospissu

September 25, 2022 07:23

@per1234 per1234 self-assigned this

Sep 25, 2022

per1234 added 2 commits

September 25, 2022 06:00

@per1234


 Add a dedicated translator guide document

0e8d576

Translation of the strings of the Arduino IDE UI is a valuable contribution which helps to make Arduino accessible to
everyone around the world.
Localization of the Arduino-specific strings of the IDE is done in the "Arduino IDE 2.0" project on Transifex.
Previously, the "Translation" row in the contribution methods summary table in the contributor guide entry page simply
linked to that project.
Arduino IDE also uses localized strings from several other sources:
- VS Code language packs
- Arduino CLI
Users may notice unlocalized strings or errors or areas for improvement in the existing translations and wish to
contribute translations. For this reason, it is important to also provide instructions for contributing to those other
localization data sources. The contribution methods summary table can not effectively accommodate that additional
content so a dedicated document is added for the purpose. This will also allow linking directly to that document from
related documentation or conversations.

@per1234


 Add readme for localization data

6d11243

Arduino IDE has been translated to several languages.
The localization process follows the following steps:
1. An English language source string is defined in the Arduino IDE codebase
2. The source string is pushed to Transifex
3. Community translators localize the string
4. The localization data is pulled into the Arduino IDE repository
5. The localization data is incorporated into the Arduino IDE distribution
Experience with maintenance of Arduino's localized projects indicates that the data files generated at step (4) can
appear to be the appropriate place to make edits for casual contributors not familiar with the project's sophisticated
internationalization infrastructure.
Since those files are generated by automated systems, any edits made there would only be overwritten, so it is important
to clearly communicate the correct way to make enhancements or corrections to these strings. This is accomplished by a
local readme file most likely to be seen by those working in the folder containing these files, which supplements the
existing information about translation in the project's translation guide.

kittaakos

kittaakos approved these changes

Sep 26, 2022

View reviewed changes