Skip to content

Commit 5540c37

Browse files
goanpecagoanpeca
committed
Update maintainers documentation
1 parent dd374fb commit 5540c37

1 file changed

Lines changed: 123 additions & 60 deletions

File tree

‎content/docs.md‎

Lines changed: 123 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ creating a separate repository for the translations under
3535
https://github.com/scientific-python-translations. To get you started with the project
3636
repository we provide a [translations-cookiecutter](https://github.com/Scientific-Python-Translations/translations-cookiecutter) template.
3737

38-
This template includes the necessary workflows that will run periodically to keep the infrastructure in sync. See [](#automations) for more details.
38+
This template includes the necessary workflows that will run periodically to keep the infrastructure in sync. See [](#automation-details) for more information.
3939

4040
### Announce your project to potential translators
4141

@@ -49,28 +49,15 @@ later.
4949
You can find potential translators by reaching out in the `#translation` channel
5050
on the [Scientific Python Discord server](https://discord.com/invite/vur45CbwMz).
5151

52-
## Automation details
53-
54-
Once a GitHub repository has been synced to Crowdin using the Scientific Python
55-
set up, the
56-
[`create_branch_for_language.sh` script](https://github.com/Scientific-Python-Translations/automations/blob/main/scripts/create_branch_for_language.sh)
57-
is used to create a new branch including all (and only) commits from Crowdin's
58-
branch for a particular language of interest. This script is useful because:
59-
60-
1. Crowdin will keep commits for all the available languages under translation
61-
in the same branch. However, we prefer to be able to create pull requests for
62-
one language at a time to keep Pull Request reviews smaller and easier to manage.
52+
### Crowdin integration
6353

64-
2. There are times when translations must be edited manually (outside of
65-
Crowdin) due to incorrect segmentation of the content into strings for
66-
translation. Crowdin's branch can only be edited through the Crowdin UI, and
67-
commits pushed to it outside of Crowdin will be lost when the branch is
68-
synced. By creating a new branch with only the commits we are interested in,
69-
we can bypass this limitation.
70-
71-
Ideally you will **not** have to run the `create_branch_for_language.sh` script
72-
directly, but can include it as part of your website deployment process (see,
73-
for example, [numpy/numpy.org#772](https://github.com/numpy/numpy.org/pull/772))
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+
[Scientific-Python-Translations/scipy.org-translations#187](https://github.com/Scientific-Python-Translations/scipy.org-translations/pull/187) for an
58+
example). If your website is set up through the Scientific Python Translations
59+
org, this PR will should have the `do-not-merge` label applied to it to ensure the PR
60+
will not be merged accidentally.
7461

7562
{{< admonition important >}}
7663
To prevent future conflicts with the GitHub/Crowdin integration, it is important
@@ -82,6 +69,120 @@ To do this, navigate to your project's Settings in Crowdin, select Import and un
8269

8370
{{< /admonition >}}
8471

72+
73+
## Automation details
74+
75+
### Cookiecutter Template
76+
77+
Use the cookiecutter template to generate a translation-ready repo:
78+
79+
```bash
80+
cookiecutter gh:Scientific-Python-Translations/translations-cookiecutter
81+
```
82+
83+
When prompted, enter the details for your project (e.g. project name, organization, base branch). The structure will include necessary metadata, content folders, and pre-commit configuration. See the [Cookiecutter repository](https://github.com/Scientific-Python-Translations/translations-cookiecutter) for more information.
84+
85+
### Sync Content from the Source Repo
86+
87+
The `sync_content.yml` github workflow is in charge of keeping the **original source content** in sync with the translations repository within the Scientific Python Translations organization.
88+
89+
This workflow uses the `content-sync` [Github action](https://github.com/Scientific-Python-Translations/content-sync).
90+
91+
### Example: Sync Scipy content
92+
93+
```yaml
94+
name: Sync Content
95+
on:
96+
schedule:
97+
- cron: '0 5 * * *'
98+
workflow_dispatch:
99+
jobs:
100+
sync:
101+
runs-on: ubuntu-latest
102+
steps:
103+
- name: Sync Scipy Content
104+
uses: Scientific-Python-Translations/content-sync@main
105+
with:
106+
source-repo: "scipy/scipy.org"
107+
source-folder: "scipy.org/content/en/"
108+
source-ref: "main"
109+
translations-repo: "Scientific-Python-Translations/scipy.org-translations"
110+
translations-folder: "scipy.org-translations/content/en/"
111+
translations-ref: "main"
112+
# These are provided by the Scientific Python Project and allow
113+
# automation with bots
114+
gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
115+
passphrase: ${{ secrets.PASSPHRASE }}
116+
token: ${{ secrets.TOKEN }}
117+
```
118+
119+
This ensures your translation repo always has the latest source material in English. If the source content has changed since the latest workflow run,
120+
the translations bot will automatically create a Pull Request, with signed commits, and merge it automatically.
121+
122+
### Pull Translations from Crowdin
123+
124+
The `sync_tarnslations.yml` github workflow is in charge of keeping the **translated content** in sync with the translations repository within the Scientific Python Translations organization.
125+
126+
This workflow uses the `translations-sync` [Github action](https://github.com/Scientific-Python-Translations/translations-sync).
127+
128+
#### Example: Sync Scipy.org translations
129+
130+
```yaml
131+
name: Sync Translations
132+
on:
133+
# schedule:
134+
# - cron: '0 12 * * MON' # Every Monday at noon
135+
workflow_dispatch:
136+
jobs:
137+
build:
138+
runs-on: ubuntu-latest
139+
steps:
140+
- name: Sync Scipy translations
141+
uses: Scientific-Python-Translations/translations-sync@main
142+
with:
143+
# Provided by user
144+
crowdin-project: "scipy.org"
145+
source-repo: "scipy/scipy.org"
146+
source-folder: "scipy.org/content/en/"
147+
source-ref: "main"
148+
translations-repo: "Scientific-Python-Translations/scipy.org-translations"
149+
translations-folder: "scipy.org-translations/content/en/"
150+
translations-ref: "main"
151+
translation-percentage: "90"
152+
approval-percentage: "0"
153+
use-precommit: "true"
154+
create-toml-file: "true"
155+
# Provided by organization secrets
156+
gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
157+
passphrase: ${{ secrets.PASSPHRASE }}
158+
token: ${{ secrets.TOKEN }}
159+
crowdin-token: ${{ secrets.CROWDIN_TOKEN }}
160+
```
161+
162+
Everytime this workflow runs, the translations bot will check for the available languages and check if they meet the translation percentage (90% by default) and approval percentage (0% by default). For every language that passes the criteria, which can be defined by the project mainatiners, a new Pull Request with signed commits will be created in the translations repository and the source repository.
163+
164+
To gather information on translators, an additional Pull Request will be created on the translations repository with a `translators.yml` file that lists the details such as username, fullname and avatar from the crowdin site.
165+
166+
All Pull Requests created by the Automations Bot on the translation repositories, will be automatically merged.
167+
168+
### Cleaning up
169+
170+
After merging the translations PR, the Crowdin service branch (by default, named `l10n_main`) may 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.
171+
172+
### The Translations Bot
173+
174+
All automations and pull requests are performed by:
175+
[**@scientificpythontranslations**](https://github.com/scientificpythontranslations)
176+
177+
Make sure to grant the bot appropriate repository permissions and exempt it from branch protection rules if needed.
178+
179+
### 📚 Additional Resources
180+
181+
- [How to Translate Content](https://scientific-python-translations.github.io/translate/)
182+
- [FAQ](https://scientific-python-translations.github.io/faq/)
183+
- [Crowdin Setup](https://crowdin.com/)
184+
- [Scientific Python Discord – `#translation`](https://scientific-python.org/community/)
185+
85186
## Setting up a language switcher
86187

87188
This work is in progress - follow (issue #) for details.
@@ -100,41 +201,3 @@ Translations may not always be up to date for items such as news items and
100201
release announcements. In this case, your project can decide what to do with
101202
these items (for example, keep them in English or hide them from the deployed
102203
site.)
103-
104-
105-
106-
107-
----
108-
109-
110-
### Merging translations
111-
112-
As translators work on the Crowdin platform, a Pull Request is automatically
113-
created in the project repository. This PR **should not** be merged, as it
114-
contains all translations for all languages (see
115-
[Scientific-Python-Translations/scipy.org-translations#187](https://github.com/Scientific-Python-Translations/scipy.org-translations/pull/187) for an
116-
example). If your website is set up through the Scientific Python Translations
117-
org, this PR will should have the `do-not-merge` label applied to it to ensure the PR
118-
will not be merged accidentally.
119-
120-
After translations for a language are completed and ready to be deployed, you
121-
should:
122-
123-
1. Go to the repository corresponding to your project's sources under
124-
https://github.com/Scientific-Python-Translations
125-
2. Go to the Actions tab
126-
3. Manually trigger the "Create translations PR" workflow, with the language
127-
code for your language of interest as input.
128-
129-
<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>
130-
131-
<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>
132-
133-
After these steps, a PR will be created to your website repo with the
134-
translations for the language you selected (see
135-
[numpy/numpy.org#774](https://github.com/numpy/numpy.org/pull/774) for an example.) This PR should be
136-
merged when you are ready to publish the translations.
137-
138-
### Cleaning up
139-
140-
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.

0 commit comments

Comments
 (0)