docs/source/developer/internationalization.md
% Copyright (c) Jupyter Development Team.
% Distributed under the terms of the Modified BSD License.
This section describes the various elements at play to create localized strings for JupyterLab.
Four elements are used to handle the internationalization of JupyterLab:
The language-packs repository is the main entry point. It interacts with Crowdin to publish
newer source strings and get the latest translation. It also creates and updates the language packs.
And finally it publishes them. All those actions are carried out using helpers defined in
jupyterlab-translate and the package template.
The workflows at play will be described next, in the order they are usually called.
:::{note} Automatic tasks are carried out through the jupyterlab-bot. To do that, that bot has access to the GitHub repository, the Crowdin project and all language packs projects on PyPI. :::
Source strings are extracted for JupyterLab and a list of extensions at a given version defined in repository-map.yaml file in language-packs repository. The workflow to trigger an update is as follow:
repository-map.yaml by adding new repositories and/or updating the target version.:::{note} Translating on Crowdin can be difficult when no sufficient context information is present, especially for Jupyter-specific terms. While some technically skilled translators will navigate to the codebase to check the context of a string, it is not an efficient workflow and prevents other translators from contributing. To enable more translators to contribute, and achieve higher accuracy of translations we should provide translators with annotated screenshots of the relevant usage of specific translatable strings (see Crowdin guide on screenshots). :::
:::{note} Crowdin is uploading automatically its source strings using GitHub Integration set up with the Crowdin account of jupyterlab-bot.
The script used for this workflow is 02_update_catalogs.py. :::
The new and/or updated translation are automatically pushed to the language-packs repository. The workflow is as follow:
l10n_master.:::{note} Crowdin is automatically uploading the translation using GitHub Integration set up with the Crowdin account of jupyterlab-bot. Hence the commits and pull request is attributed to the bot.
If the branch is deleted, it will be re-created. :::
:::{warning}
To avoid merge conflicts on those translation update pull requests, they should be merged before
any repository-map.yaml pull requests as those will update the source strings. If not, the pull
requests updating the source strings need to be closed in order for the Crowdin integration to
re-open the PR.
:::
(language-update)=
Before a release of updated language packs with new translations from Crowdin the language packs need to be prepared by updating the version strings of all packages. This is done by manually triggering the Prepare language packs for release workflow.
There is one optional setting:
rev that will bump the post number.:alt: The "Prepare language packs for release" workflow on GitHub Actions.
The workflow is:
:::{note} The version policy for the language packs is to follow major and minor version numbers of JupyterLab and bumping the post number for any intermediate updates. The version of all language packs is identical to ease maintenance.
The script used for this workflow is 03_prepare_release.py. :::
Each time package version is modified the Create Release and publish packages will be automatically triggered. Its steps are:
Check that all language packs have identical versions
Start a matrix of job (one for each language pack)
:::{note} Publication is done using jupyterlab-bot credentials on all PyPI projects.
Conda recipe should be updated by the auto-tick bot of conda-forge. :::
This requires the following manual actions to be executed (in that order):
language-update workflow