Skip to content

Commit c281b29

Browse files
Abdur-rahmaanJAbdur-rahmaanJ
authored
Merge pull request #87 from flpm/flpm-blog-post
Blog post about steps to update PO files with new versions of the English Flask doc
2 parents ed55cc6 + 6b0fb48 commit c281b29

File tree

1 file changed

+228
-0
lines changed

1 file changed

+228
-0
lines changed

‎data/blog/main/how-sync-translations.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
title: How to synchronize translations
2+
summary: Steps to update translations
3+
authors: flpm
4+
date: May 21, 2024
5+
tags: translation
6+
slug: how-sync-translations
7+
8+
One of the challenges of maintaining different translations of documentation for an open source project is keeping up with the changes to the documentation in its original language as the project evolves and new releases are issued and updates are made.
9+
10+
As I learned during a recent open source sprint organized at PyCon US 2024, in the case of Flask’s documentation, there is an additional challenge of working in separate repositories for each language the documentation is translated into.
11+
12+
This post will document a simple process that the contributors and maintainers of the different language translations can use to keep their repositories up to date with the latest version of Flask’s documentation in English.
13+
14+
## Set up your local environment
15+
16+
First, fork the translation repository for the language you will be working on from the Flask CWG GitHub organization into your personal GitHub space. If you need, you can find more information about forking in the GitHub documentation [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
17+
18+
Once the forked repository has been created, clone it on your computer. If you are not familiar with this step, more details are available in the GitHub documentation [here](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
19+
20+
At this point, you will have the latest version of the translation for the language you are working on.
21+
22+
## Add the main Flask repository as a new git remote
23+
24+
_Quick note: The command outputs you will see below show details like tags and commit hashes from the time this post was written. When you execute them, you will probably see different values._
25+
26+
To access the original English documentation, you will need to set a new git remote repository that points to the main Flask repository:
27+
28+
```shell
29+
$ git remote add flask https://github.com/pallets/flask.git
30+
```
31+
32+
Then, fetch the data from it.
33+
34+
```shell
35+
$ git fetch flask
36+
remote: Enumerating objects: 24785, done.
37+
remote: Counting objects: 100% (249/249), done.
38+
remote: Compressing objects: 100% (187/187), done.
39+
remote: Total 24785 (delta 105), reused 166 (delta 53), pack-reused 24536
40+
Receiving objects: 100% (24785/24785), 10.22 MiB | 16.41 MiB/s, done.
41+
Resolving deltas: 100% (16592/16592), done.
42+
From https://github.com/pallets/flask
43+
* [new branch] 0.12.x -> flask/0.12.x
44+
* [new branch] 1.0.x -> flask/1.0.x
45+
* [new branch] 1.1.x -> flask/1.1.x
46+
* [new branch] 2.0.x -> flask/2.0.x
47+
* [new branch] 2.1.x -> flask/2.1.x
48+
* [new branch] 2.2.x -> flask/2.2.x
49+
* [new branch] 2.3.x -> flask/2.3.x
50+
* [new branch] 3.0.x -> flask/3.0.x
51+
* [new branch] main -> flask/main
52+
* [new tag] 1.1.4 -> 1.1.4
53+
(...)
54+
* [new tag] 2.3.3 -> 2.3.3
55+
* [new tag] 3.0.1 -> 3.0.1
56+
* [new tag] 3.0.2 -> 3.0.2
57+
* [new tag] 3.0.3 -> 3.0.3
58+
```
59+
60+
## Update the English source of your translation
61+
62+
Start by creating a new branch:
63+
64+
```shell
65+
$ git checkout -b update-docs main
66+
Switched to a new branch 'update-docs'
67+
```
68+
69+
Then, delete the current English documentation .rst files in the translation repository (this step is necessary to ensure we don't keep old files that may have been removed in the English version):
70+
71+
```shell
72+
$ rm -r ./docs/*.rst
73+
```
74+
75+
In discussion with the Flask project maintainers, the Flask CWG has decided to keep the translations synchronized with the documentation of the latest released version of Flask. To find the most recent version of the English documentation, locate the latest release tag:
76+
77+
```shell
78+
$ git tag --sort=-taggerdate | head -n 1
79+
3.0.3
80+
81+
```
82+
83+
Once you have the right tag, you can checkout the right version of the documentation folder into your new branch:
84+
85+
```shell
86+
$ git checkout 3.0.3 ./docs/
87+
Updated 14 paths from a7d387fa
88+
89+
$ git status
90+
On branch update-docs
91+
Changes to be committed:
92+
(use "git restore --staged <file>..." to unstage)
93+
modified: docs/api.rst
94+
modified: docs/conf.py
95+
modified: docs/config.rst
96+
modified: docs/errorhandling.rst
97+
modified: docs/index.rst
98+
modified: docs/license.rst
99+
modified: docs/logging.rst
100+
modified: docs/patterns/appdispatch.rst
101+
modified: docs/patterns/javascript.rst
102+
modified: docs/patterns/packages.rst
103+
modified: docs/patterns/sqlalchemy.rst
104+
modified: docs/server.rst
105+
modified: docs/testing.rst
106+
modified: docs/tutorial/install.rst
107+
(...)
108+
```
109+
110+
Let's commit these changes to the branch:
111+
112+
```shell
113+
git commit -m 'Updated the English documentation'
114+
[update-docs 2993d997] Updated the English documentation
115+
14 files changed, 58 insertions(+), 89 deletions(-)
116+
117+
```
118+
119+
Next, to ensure you keep up with the documentation building requirements, update the requirements folder as well.
120+
121+
```shell
122+
git checkout 3.0.3 ./requirements/
123+
Updated 0 paths from a7d387fa
124+
125+
```
126+
127+
In this case, no files were updated ("Updated 0 paths"). But, if the requirements change, we will need those changes as well.
128+
129+
## Prepare a virtual environment to build the documentation
130+
131+
Prepare to build the documentation by creating a virtual environment and installing the necessary requirements. Assuming you have virtualenv installed, run the following commands:
132+
133+
```shell
134+
$ python -m venv .venv
135+
$ source .venv/bin/activate
136+
(.venv) $ pip install -r ./requirements/docs.txt
137+
Collecting alabaster==0.7.16
138+
Using cached alabaster-0.7.16-py3-none-any.whl (13 kB)
139+
Collecting babel==2.14.0
140+
Downloading Babel-2.14.0-py3-none-any.whl (11.0 MB)
141+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.0/11.0 MB 31.3 MB/s eta 0:00:00
142+
Collecting certifi==2024.2.2
143+
Downloading certifi-2024.2.2-py3-none-any.whl (163 kB)
144+
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 163.8/163.8 KB 12.0 MB/s eta 0:00:00
145+
Collecting charset-normalizer==3.3.2
146+
Using cached charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (142 kB)
147+
(...)
148+
```
149+
150+
## Recreate the translation templates (`.pot` files)
151+
152+
Before you can update the translation files for the language you are working on, you need to recreate the translation template files with the latest version of the documentation you just copied. This is an intermediate step as you will not be working on these files directly. They are stored in the `./_build/gettext` folder.
153+
154+
```shell
155+
$ cd ./docs
156+
$ make gettext
157+
Running Sphinx v7.2.6
158+
making output directory... done
159+
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
160+
loading intersphinx inventory from https://werkzeug.palletsprojects.com/objects.inv...
161+
loading intersphinx inventory from https://click.palletsprojects.com/objects.inv...
162+
loading intersphinx inventory from https://jinja.palletsprojects.com/objects.inv...
163+
loading intersphinx inventory from https://itsdangerous.palletsprojects.com/objects.inv...
164+
loading intersphinx inventory from https://docs.sqlalchemy.org/objects.inv...
165+
(...)
166+
```
167+
168+
## Update the translation files (`.po` files)
169+
170+
Before we can run the next step, you need to install sphinx-intl in your current virtual environment. Since this is a requirement for the translation work, it is not part of the original documentation requirements:
171+
172+
```shell
173+
$ pip install sphinx-intl
174+
Collecting sphinx-intl
175+
Downloading sphinx_intl-2.2.0-py3-none-any.whl (13 kB)
176+
Requirement already satisfied: babel in /home/felipe/github/flaskcwg/flask-docs-es/venv/lib/python3.10/site-packages (from sphinx-intl) (2.14.0)
177+
Requirement already satisfied: setuptools in /home/felipe/github/flaskcwg/flask-docs-es/venv/lib/python3.10/site-packages (from sphinx-intl) (59.6.0)
178+
Requirement already satisfied: sphinx in /home/felipe/github/flaskcwg/flask-docs-es/venv/lib/python3.10/site-packages (from sphinx-intl) (7.2.6)
179+
(...)
180+
```
181+
182+
You are now ready to update the translation for the language you are working on. In the example below, we are working with the Spanish translation (language code `es`). Remember to replace the language code for the one for your language:
183+
184+
```shell
185+
$ sphinx-intl update -p _build/gettext -l es
186+
Update: locales/es/LC_MESSAGES/api.po +19, -26
187+
Not Changed: locales/es/LC_MESSAGES/config.po
188+
Not Changed: locales/es/LC_MESSAGES/templating.po
189+
Not Changed: locales/es/LC_MESSAGES/license.po
190+
Not Changed: locales/es/LC_MESSAGES/blueprints.po
191+
Update: locales/es/LC_MESSAGES/testing.po +1, -2
192+
Not Changed: locales/es/LC_MESSAGES/views.po
193+
(...)
194+
```
195+
196+
At this point, the `.po` files in the `./locales` folder have been updated with the latest version of the English documentation.
197+
198+
The update process will preserve the current translations and add new strings that might have been added to the English documentation.
199+
200+
If some of the already translated strings changed in the English documentation, the corresponding entries in the .po files will be marked with the tag "fuzzy", indicating they need to be checked for accuracy.
201+
202+
For more information about the PO format, including the fuzzy tag, consult the [gettext documentation](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html).
203+
204+
## Commit the translation files
205+
206+
Add the updated translation files to the branch. You do not need to worry about the .pot files, they don't need to be stored in the repository.
207+
208+
```shell
209+
$ git add ./locales/
210+
211+
$ git status
212+
On branch update-docs
213+
Changes to be committed:
214+
(use "git restore --staged <file>..." to unstage)
215+
modified: locales/es/LC_MESSAGES/api.po
216+
new file: locales/es/LC_MESSAGES/deploying.po
217+
modified: locales/es/LC_MESSAGES/errorhandling.po
218+
new file: locales/es/LC_MESSAGES/patterns.po
219+
modified: locales/es/LC_MESSAGES/server.po
220+
modified: locales/es/LC_MESSAGES/testing.po
221+
new file: locales/es/LC_MESSAGES/tutorial.po
222+
223+
$ git commit -m 'Updated the translation files'
224+
```
225+
226+
## Make a PR
227+
228+
At this point, you are ready to create a pull request to incorporate your changes into the Flask CWG language repository. You can find more information about creating a pull request in the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

0 commit comments

Comments
 (0)