Localization data update procedure is undocumented

[502E532E]

Describe the problem

I created a pull request (#2718) that includes a new translation key. The "Check Internationalization" GitHub Actions workflow run failed on the pull request:

Run yarn i18n:check
yarn run v1.22.22
$ yarn i1[8](https://github.com/arduino/arduino-ide/actions/runs/14605714270/job/40974189197?pr=2718#step:8:9)n:generate && git add -N ./i18n && git diff --exit-code ./i18n
$ theia nls-extract -e vscode -f "+(arduino-ide-extension|electron-app|plugins)/**/*.ts?(x)" -o ./i18n/en.json
diff --git a/i18n/en.json b/i18n/en.json
index e6dbab0..5e3d1[9](https://github.com/arduino/arduino-ide/actions/runs/14605714270/job/40974189197?pr=2718#step:8:10)b 100644
--- a/i18n/en.json
+++ b/i18n/en.json
@@ -435,6 +435,7 @@
       "autoscroll": "Autoscroll",
       "carriageReturn": "Carriage Return",
       "connecting": "Connecting to '{0}' on '{1}'...",
+      "copyOutput": "Copy Output",
       "message": "Message (Enter to send message to '{0}' on '{1}')",
       "newLine": "New Line",
       "newLineCarriageReturn": "Both NL & CR",
error Command failed with exit code 1.

I had to carefully study the logs of the failed check in order to determine that I needed to run the i18n:generate Yarn script to resolve this.

The addition of new i18n keys to the codebase will be a common occurrence for contributors proposing new features, yet there is no mention of the requirement to run this command in the Development Guide, or anywhere else in the documentation.

Expected behavior

Any common operation that is required of contributors is documented.

Instructions for the procedure the contributor must follow to update the localization data files after adding an internationalization key to the codebase, or removing a key from the codebase should be provided in the "Development Guide" documentation:

https://github.com/arduino/arduino-ide/blob/main/docs/development.md#development-guide

It would also be good to ensure that information is easily discovered by the reader of the "Pull Request Guide".

Arduino IDE version

0f9f0d0

Additional context

In addition to the system that must be used by the contributor, the repository also contains a system for pushing the updated localization files to Transifex and pulling the localization data from the Transifex project.

Those contributing to the application codebase don't need to use this system, as it operates independently, but the project maintainers do need to maintain the system, so they do need to understand how it works. There is currently no documentation of this system. It would be useful to add an overview of the full i18n/l10n system. The appropriate place for that information would be in the "internal" documentation:

https://github.com/arduino/arduino-ide/tree/main/docs/internal

Here is a rough overview:

1. A developers adds or removes an internationalization key in the Arduino IDE application codebase.
2. The developer runs the i18n:generate Yarn script to update the localization data files.
3. A scheduled daily run of the "i18n-nightly-push" workflow is triggered.
4. The workflow runs the i18n:push Yarn script, which uploads the en.json file (only that file) to the "Arduino IDE 2.0" Transifex project.
5. Volunteer translators on Transifex localize any newly added content.
6. A scheduled daily run of the the "i18n-weekly-pull" workflow is triggered
7. The "i18n-weekly-pull" workflow runs the i18n:pull Yarn script, which pulls the localization data from Transifex.
8. The "i18n-weekly-pull" workflow submits a pull request for the changes to the localization data files.
9. A maintainer merges the PR at their convenience.

Related

• Free contributors from i18n data sync responsibility arduino-cli#1515

Issue checklist

• I searched for previous requests in the issue tracker
• I verified the feature was still missing when using the latest nightly build
• My request contains all necessary details