oarepo-tools
Developer tooling for OARepo packages. It provides the make-translations command, which keeps
Python/Jinja (gettext) and JavaScript (i18next) translations of a package in one set of .po
catalogues.
Requirements
- Python 3.14 (oarepo-tools 1.x). Use oarepo-tools 0.2.x for older Python versions.
- Node.js and npm, unless you run with
--without-ui.
Installation
In OARepo libraries and repositories nothing needs to be installed: oarepo-cli depends on
oarepo-tools, and ./run.sh translations runs make-translations in the project root
(extra arguments are passed through, e.g. ./run.sh translations --without-ui).
To use the command on its own, add oarepo-tools to your development dependencies, e.g. in
pyproject.toml:
[project.optional-dependencies]
dev = ["oarepo-tools"]
Usage
make-translations [CONFIG_PATH] [--without-ui]
CONFIG_PATH is the directory containing the configuration (or the configuration file itself);
it defaults to the current directory. All paths in the configuration are relative to that
directory.
- Run
make-translations. It extracts the messages from your sources and creates or updates amessages.pocatalogue for every language inbabel_output_translations. - Translate the catalogues, e.g. with Poedit or in a text editor.
- Run
make-translationsagain. It compiles the catalogues to.mofiles for Python and to i18next JSON files for JavaScript.
Use --without-ui for packages without JavaScript sources: the i18next steps are skipped and
Node.js is not needed.
Configuration
The configuration is read from the [oarepo.i18n] section of setup.cfg. If that file or
section is missing, the i18n section of oarepo.yaml is used instead.
oarepo.yaml:
i18n:
languages:
- cs
- en
babel_source_paths:
- my_package/
babel_output_translations: my_package/translations
# only needed with JavaScript sources (i.e. without --without-ui)
i18next_source_paths:
- my_package/ui/theme/assets/semantic-ui/js
i18next_output_translations: my_package/ui/theme/assets/semantic-ui/translations/my_package
setup.cfg (legacy) uses the same keys. Write list values one item per line, starting on the
line after the key; a value on the same line as the key is read as a single string.
[oarepo.i18n]
languages =
cs
en
babel_source_paths =
my_package/
babel_output_translations = my_package/translations
| Key | Required | Description |
|---|---|---|
languages |
yes | Language codes to manage. |
babel_source_paths |
yes | Directories scanned for gettext messages: *.py files, *.html and *.jinja (JinjaX) templates. |
babel_output_translations |
yes | Directory where the gettext catalogues (<lang>/LC_MESSAGES/messages.po/.mo) are generated. |
babel_input_translations |
no | Extra gettext catalogue directories (<lang>/LC_MESSAGES/*.po) merged into the output, e.g. translations generated for models. |
i18next_source_paths |
without --without-ui |
Directories scanned for i18next messages: i18next.t(...) calls and <Trans> components in *.js/*.jsx files. |
i18next_output_translations |
without --without-ui |
Directory where the i18next entrypoint and JSON catalogues are generated. |
i18next_input_translations |
no | Extra i18next catalogue directories (<lang>/translations.json) merged into the output. |
In Python, mark messages with _, gettext, lazy_gettext and the other standard gettext
functions. In JavaScript, import the generated i18next instance and use i18next.t("...") or
<Trans>.
Integrating the output
-
Register the package for Invenio translations in
pyproject.toml; the entry point names the package that contains thetranslationsdirectory:[project.entry-points."invenio_i18n.translations"] my_package = "my_package"
-
Ship the generated
.po/.mofiles with the package (hatchling includes them by default unless they are gitignored). -
i18next_output_translationscontainsi18next.js, which exports a configuredi18nextinstance, andmessages/<lang>/LC_MESSAGES/translations.json. Add a webpack alias for this directory in your theme bundle, e.g."@translations/my_package": "translations/my_package", and import it withimport { i18next } from "@translations/my_package/i18next";.
Side effects
babel.iniin the configuration directory is overwritten with the bundled version on every run; customize extraction through the configuration keys instead of editing it.i18next.jsandmessages/index.jsini18next_output_translationsare regenerated on every run.- Untranslated messages are left out of the i18next JSON files, so i18next falls back to the key (the English text).
- Unless
--without-uiis used, every run callsnpm installinside the installedoarepo_toolspackage to fetchi18next-scannerandi18next-conv, so that directory must be writable.
Contributing
See CONTRIBUTING.md. Licensed under the MIT License.
Metadata
Release files for oarepo-tools 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oarepo_tools-1.0.0.tar.gz | 11.5 kB | Without provenance | Details for oarepo_tools-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oarepo_tools-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for oarepo_tools-1.0.0-py3-none-any.whl |
Total release size: 27.1 kB
Release files / oarepo_tools-1.0.0.tar.gz
| Download URL | oarepo_tools-1.0.0.tar.gz |
|---|---|
| Size | 11.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
328dfc24deb987aeb1e67e145277171dc9104d29524671b8456b4273e8c761a7
|
|
BLAKE2b-256 checksum How to use checksums |
486f8b3a6680b11e75087032140869c09acca2a5d03371c427bd40e47913fd48
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / oarepo_tools-1.0.0-py3-none-any.whl
| Download URL | oarepo_tools-1.0.0-py3-none-any.whl |
|---|---|
| Size | 15.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c896d8f167502debe56156dd80b85603ce31f1fb14bcdd4d6ea9fb9d960edc3e
|
|
BLAKE2b-256 checksum How to use checksums |
06ca9250e98d5df7623691508bca15f943cece09b2ab54f75501b9fc2e375125
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for oarepo-tools 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.