|
| 1 | +--- |
| 2 | +title: "Maintainers' documentation" |
| 3 | +draft: false |
| 4 | +--- |
| 5 | + |
| 6 | +This page details existing patterns for setting up and deploying translations |
| 7 | +for project websites. As each project has their own set up, the patterns |
| 8 | +described here may not fit exactly, but they will help you understand the |
| 9 | +basic workflows. |
| 10 | + |
| 11 | +At least some of the tasks described here rely on scripts from |
| 12 | +https://github.com/Scientific-Python-Translations/automations/. |
| 13 | + |
| 14 | +<!-- separate actual steps maintainers need to take from internal crowdin implementation details --> |
| 15 | + |
| 16 | +## Integration with Crowdin |
| 17 | + |
| 18 | +[Crowdin](https://scientific-python.crowdin.com/) provides GitHub integration |
| 19 | +tools to sync all translated content from the Crowdin web interface into project |
| 20 | +websites and vice-versa. However, a few adaptations are needed. The following |
| 21 | +steps describe what maintainers need to do to set up the integration. See [](#automations) for more details on this script. |
| 22 | + |
| 23 | +### Setting up Crowdin |
| 24 | + |
| 25 | +Create a Crowdin project for your repository and turn on synchronization |
| 26 | +between Crowdin and your source repo. If you planning on using the |
| 27 | +[Scientific Python Crowdin workspace](https://scientific-python.crowdin.com/), |
| 28 | +please reach out to the |
| 29 | +[Scientific Python translations team on discord](https://discord.com/invite/vur45CbwMz) |
| 30 | +for help. For more information, see |
| 31 | +[Crowdin's documentation](https://support.crowdin.com/enterprise/github-integration/). |
| 32 | + |
| 33 | +To prevent extra activity in the original source repository, we recommend |
| 34 | +creating a separate repository for the translations under |
| 35 | +https://github.com/scientific-python-translations with a GitHub action to sync |
| 36 | +the translations to the original repository (see |
| 37 | +[sync.yml](https://github.com/Scientific-Python-Translations/scipy.org-translations/blob/main/.github/workflows/sync.yml) |
| 38 | +for an example). |
| 39 | + |
| 40 | +### Announce your project to potential translators |
| 41 | + |
| 42 | +After your project is set up, you will have to add translators as members to |
| 43 | +your Crowdin project so they can start translating. The general best practice is |
| 44 | +to have two people per language (one translator, one reviewer) to ensure the |
| 45 | +quality of the translations. However, your translations will not be published |
| 46 | +until you approve them, so you can start with one translator and add a reviewer |
| 47 | +later. |
| 48 | + |
| 49 | +You can find potential translators by reaching out in the `#translation` channel |
| 50 | +on the [Scientific Python Discord server](https://discord.com/invite/vur45CbwMz). |
| 51 | + |
| 52 | +### Merging translations |
| 53 | + |
| 54 | +As translators work on the Crowdin platform, a Pull Request is automatically |
| 55 | +created in the project repository. This PR **should not** be merged, as it |
| 56 | +contains all translations for all languages (see |
| 57 | +[numpy/numpy.org#778](https://github.com/numpy/numpy.org/pull/778) for an |
| 58 | +example). If your website is set up through the Scientific Python Translations |
| 59 | +org, this PR will have the `do-not-merge` label applied to it. |
| 60 | + |
| 61 | +After translations for a language are completed and ready to be deployed, you |
| 62 | +should: |
| 63 | + |
| 64 | +1. Go to the repository corresponding to your project's sources under |
| 65 | + https://github.com/Scientific-Python-Translations |
| 66 | +2. Go to the Actions tab |
| 67 | +3. Manually trigger the "Create translations PR" workflow, with the language |
| 68 | + code for your language of interest as input. |
| 69 | + |
| 70 | +<center><img alt="Screenshot of the Actions tab from GitHub, with the Create translations PR workflow highlighted." src="../images/create_translations.png" width=800/></center> |
| 71 | + |
| 72 | +<center><img alt="Screenshot of the Run workflow dialog from GitHub, with an input field labeled Crowding language code for the language of interest" src="../images/run_workflow.png" width=800/></center> |
| 73 | + |
| 74 | +After these steps, a PR will be created to your website repo with the |
| 75 | +translations for the language you selected (see |
| 76 | +[numpy/numpy.org#774](https://github.com/numpy/numpy.org/pull/774) for an example.) This PR should be |
| 77 | +merged when you are ready to publish the translations. |
| 78 | + |
| 79 | +### Cleaning up |
| 80 | + |
| 81 | +After merging the translations PR, the Crowdin service branch (by default, named `l10n_main`) will have merge conflicts with `main`. To fix this, delete the Crowdin service branch. Crowdin will automatically recreate the service branch with merge conflicts resolved. This same process can also be used to resolve merge conflicts if translations are updated outside of Crowdin. |
| 82 | + |
| 83 | +## Automation details |
| 84 | + |
| 85 | +Once a GitHub repository has been synced to Crowdin using the Scientific Python |
| 86 | +set up, the |
| 87 | +[`create_branch_for_language.sh` script](https://github.com/Scientific-Python-Translations/automations/blob/main/scripts/create_branch_for_language.sh) |
| 88 | +is used to create a new branch including all (and only) commits from Crowdin's |
| 89 | +branch for a particular language of interest. This script is useful because: |
| 90 | + |
| 91 | +1. Crowdin will keep commits for all the available languages under translation |
| 92 | + in the same branch. However, we prefer to be able to create pull requests for |
| 93 | + one language at a time to keep Pull Request reviews smaller and easier to manage. |
| 94 | + |
| 95 | +2. There are times when translations must be edited manually (outside of |
| 96 | + Crowdin) due to incorrect segmentation of the content into strings for |
| 97 | + translation. Crowdin's branch can only be edited through the Crowdin UI, and |
| 98 | + commits pushed to it outside of Crowdin will be lost when the branch is |
| 99 | + synced. By creating a new branch with only the commits we are interested in, |
| 100 | + we can bypass this limitation. |
| 101 | + |
| 102 | +Ideally you will **not** have to run the `create_branch_for_language.sh` script |
| 103 | +directly, but can include it as part of your website deployment process (see, |
| 104 | +for example, [numpy/numpy.org#772](https://github.com/numpy/numpy.org/pull/772)) |
| 105 | + |
| 106 | +{{< admonition important >}} |
| 107 | +To prevent future conflicts with the GitHub/Crowdin integration, it is important |
| 108 | +that you configure Crowdin to have duplicate strings share the same translation. |
| 109 | +To do this, navigate to your project's Settings in Crowdin, select Import and under |
| 110 | +"Source strings" -> "Duplicates" choose "Hide (regular detection)". |
| 111 | + |
| 112 | +<center><img alt="Screenshot of the Crowdin Settings showing the 'Hide (regular detection)' option." src="../images/duplicate_strings.png" width=800/></center> |
| 113 | + |
| 114 | +{{< /admonition >}} |
| 115 | + |
| 116 | +## Setting up a language switcher |
| 117 | + |
| 118 | +This work is in progress - follow (issue #) for details. |
| 119 | + |
| 120 | +### Scientific Python Hugo Theme |
| 121 | + |
| 122 | +### PyData Sphinx Theme |
| 123 | + |
| 124 | +This work is in progress - follow [pydata/pydata-sphinx-theme#507](https://github.com/pydata/pydata-sphinx-theme/issues/507) for details. |
| 125 | + |
| 126 | +## Known limitations |
| 127 | + |
| 128 | +### Missing translations |
| 129 | + |
| 130 | +Translations may not always be up to date for items such as news items and |
| 131 | +release announcements. In this case, your project can decide what to do with |
| 132 | +these items (for example, keep them in English or hide them from the deployed |
| 133 | +site.) |
0 commit comments