mirror of
https://github.com/apache/superset.git
synced 2026-04-19 08:04:53 +00:00
feat: bake translations as part of the build processes (#28483)
This commit is contained in:
Maxime Beauchemin
committed by
GitHub
GitHub
parent
78aa79bb15
commit
8d57a35531
@@ -737,97 +737,6 @@ npm run storybook
|
||||
|
||||
When contributing new React components to Superset, please try to add a Story alongside the component's `jsx/tsx` file.
|
||||
|
||||
## Translating
|
||||
|
||||
We use [Flask-Babel](https://python-babel.github.io/flask-babel/) to translate Superset.
|
||||
In Python files, we import the magic `_` function using:
|
||||
|
||||
```python
|
||||
from flask_babel import lazy_gettext as _
|
||||
```
|
||||
|
||||
then wrap our translatable strings with it, e.g. `_('Translate me')`.
|
||||
During extraction, string literals passed to `_` will be added to the
|
||||
generated `.po` file for each language for later translation.
|
||||
|
||||
At runtime, the `_` function will return the translation of the given
|
||||
string for the current language, or the given string itself
|
||||
if no translation is available.
|
||||
|
||||
In TypeScript/JavaScript, the technique is similar:
|
||||
we import `t` (simple translation), `tn` (translation containing a number).
|
||||
|
||||
```javascript
|
||||
import { t, tn } from "@superset-ui/translation";
|
||||
```
|
||||
|
||||
### Enabling language selection
|
||||
|
||||
Add the `LANGUAGES` variable to your `superset_config.py`. Having more than one
|
||||
option inside will add a language selection dropdown to the UI on the right side
|
||||
of the navigation bar.
|
||||
|
||||
```python
|
||||
LANGUAGES = {
|
||||
'en': {'flag': 'us', 'name': 'English'},
|
||||
'fr': {'flag': 'fr', 'name': 'French'},
|
||||
'zh': {'flag': 'cn', 'name': 'Chinese'},
|
||||
}
|
||||
```
|
||||
|
||||
### Updating language files
|
||||
|
||||
```bash
|
||||
./scripts/babel_update.sh
|
||||
```
|
||||
|
||||
This script will
|
||||
|
||||
1. update the template file `superset/translations/messages.pot` with current application strings.
|
||||
2. update language files with the new extracted strings.
|
||||
|
||||
You can then translate the strings gathered in files located under
|
||||
`superset/translation`, where there's one per language. You can use [Poedit](https://poedit.net/features)
|
||||
to translate the `po` file more conveniently.
|
||||
There are some [tutorials in the wiki](https://wiki.lxde.org/en/Translate_*.po_files_with_Poedit).
|
||||
|
||||
In the case of JS translation, we need to convert the PO file into a JSON file, and we need the global download of the npm package po2json.
|
||||
|
||||
```bash
|
||||
npm install -g po2json
|
||||
```
|
||||
|
||||
To convert all PO files to formatted JSON files you can use the `po2json.sh` script.
|
||||
|
||||
```bash
|
||||
./scripts/po2json.sh
|
||||
```
|
||||
|
||||
If you get errors running `po2json`, you might be running the Ubuntu package with the same
|
||||
name, rather than the Node.js package (they have a different format for the arguments). If
|
||||
there is a conflict, you may need to update your `PATH` environment variable or fully qualify
|
||||
the executable path (e.g. `/usr/local/bin/po2json` instead of `po2json`).
|
||||
If you get a lot of `[null,***]` in `messages.json`, just delete all the `null,`.
|
||||
For example, `"year":["年"]` is correct while `"year":[null,"年"]`is incorrect.
|
||||
|
||||
For the translations to take effect we need to compile translation catalogs into binary MO files.
|
||||
|
||||
```bash
|
||||
pybabel compile -d superset/translations
|
||||
```
|
||||
|
||||
### Creating a new language dictionary
|
||||
|
||||
To create a dictionary for a new language, run the following, where `LANGUAGE_CODE` is replaced with
|
||||
the language code for your target language, e.g. `es` (see [Flask AppBuilder i18n documentation](https://flask-appbuilder.readthedocs.io/en/latest/i18n.html) for more details):
|
||||
|
||||
```bash
|
||||
pip install -r superset/translations/requirements.txt
|
||||
pybabel init -i superset/translations/messages.pot -d superset/translations -l LANGUAGE_CODE
|
||||
```
|
||||
|
||||
Then, [Updating language files](#updating-language-files).
|
||||
|
||||
## Tips
|
||||
|
||||
### Adding a new datasource
|
||||
|
||||
@@ -459,7 +459,7 @@ npm run storybook
|
||||
|
||||
When contributing new React components to Superset, please try to add a Story alongside the component's `jsx/tsx` file.
|
||||
|
||||
## Contribute Translations
|
||||
## Contributing Translations
|
||||
|
||||
We use [Flask-Babel](https://python-babel.github.io/flask-babel/) to translate Superset.
|
||||
In Python files, we use the following
|
||||
@@ -538,18 +538,17 @@ pybabel init -i superset/translations/messages.pot -d superset/translations -l f
|
||||
|
||||
### Extracting new strings for translation
|
||||
|
||||
This step needs to be done every time application strings change. This happens fairly
|
||||
frequently, so if you want to ensure that your translation has good coverage, this
|
||||
step needs to be run fairly frequently and the updated strings merged to the upstream
|
||||
codebase via PRs. To update the template file `superset/translations/messages.pot`
|
||||
with current application strings, run the following command:
|
||||
Periodically, when working on translations, we need to extract the strings from both the
|
||||
backend and the frontend to compile a list of all strings to be translated. It doesn't
|
||||
happen automatically and is a required step to gather the strings and get them into the
|
||||
`.po` files where they can be translated, so that they can then be compiled.
|
||||
|
||||
This script does just that:
|
||||
|
||||
```bash
|
||||
pybabel extract -F superset/translations/babel.cfg -o superset/translations/messages.pot -k _ -k __ -k t -k tn -k tct .
|
||||
./scripts/translations/babel_update.sh
|
||||
```
|
||||
|
||||
Do not forget to update this file with the appropriate license information.
|
||||
|
||||
### Updating language files
|
||||
|
||||
Run the following command to update the language files with the new extracted strings.
|
||||
@@ -575,27 +574,15 @@ case of the Finnish translation, this would be `superset/translations/fi/LC_MESS
|
||||
### Applying translations
|
||||
|
||||
To make the translations available on the frontend, we need to convert the PO file into
|
||||
a JSON file. To do this, we need to globally install the npm package `po2json`.
|
||||
a collection of JSON files. To convert all PO files to formatted JSON files you can use
|
||||
the build-translation script
|
||||
|
||||
```bash
|
||||
npm install -g po2json
|
||||
npm run build-translation
|
||||
```
|
||||
|
||||
To convert all PO files to formatted JSON files you can use the `po2json.sh` script.
|
||||
|
||||
```bash
|
||||
./scripts/po2json.sh
|
||||
```
|
||||
|
||||
If you get errors running `po2json`, you might be running the Ubuntu package with the same
|
||||
name, rather than the Node.js package (they have a different format for the arguments). If
|
||||
there is a conflict, you may need to update your `PATH` environment variable or fully qualify
|
||||
the executable path (e.g. `/usr/local/bin/po2json` instead of `po2json`).
|
||||
If you get a lot of `[null,***]` in `messages.json`, just delete all the `null,`.
|
||||
For example, `"year":["年"]` is correct while `"year":[null,"年"]`is incorrect.
|
||||
|
||||
Finally, for the translations to take effect we need to compile translation catalogs into
|
||||
binary MO files.
|
||||
binary MO files for the backend using pybabel.
|
||||
|
||||
```bash
|
||||
pybabel compile -d superset/translations
|
||||
|
||||
Reference in New Issue
Block a user