forked from Github-Mirrors/canaille
doc: better translation documentation
This commit is contained in:
Éloi Rivard
parent
61df50aa39
commit
97470bffe6
5 changed files with 113 additions and 16 deletions
|
|
@ -144,11 +144,11 @@ The dynamical parts of the interface use `htmx <https://htmx.org/>`_.
|
|||
not depend on jQuery at all.
|
||||
See the `related issue <https://gitlab.com/yaal/canaille/-/issues/130>`_.
|
||||
|
||||
Translation
|
||||
-----------
|
||||
Translations
|
||||
------------
|
||||
|
||||
Translations are done with `Weblate <https://hosted.weblate.org/engage/canaille/>`_,
|
||||
so all translation contributions should be done there.
|
||||
.. include:: ../canaille/translations/README.md
|
||||
:parser: myst_parser.sphinx_
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
|
|
|||
|
|
@ -1,27 +1,38 @@
|
|||
Translations are done with [weblate](https://hosted.weblate.org/projects/canaille/canaille/).
|
||||
Those commands are there as documentation, only the message extraction is needed for contributors.
|
||||
Translations are done with [Weblate](https://hosted.weblate.org/projects/canaille/canaille/).
|
||||
|
||||
The following commands are there as documentation, only the message extraction is needed for contributors.
|
||||
All the other steps are automatically done with Weblate.
|
||||
|
||||
Extract the messages with:
|
||||
|
||||
```
|
||||
## Message extraction
|
||||
|
||||
After you have edited translatable strings, you should extract the messages with:
|
||||
|
||||
```bash
|
||||
pybabel extract --mapping-file canaille/translations/babel.cfg --copyright-holder="Yaal Coop" --output-file canaille/translations/messages.pot canaille
|
||||
```
|
||||
|
||||
Add a new language with:
|
||||
## Language addition
|
||||
|
||||
```
|
||||
You can add a new language manually with the following command, however this should not be needed as Weblate takes car of this:
|
||||
|
||||
```bash
|
||||
pybabel init --input-file canaille/translations/messages.pot --output-dir canaille/translations --locale <LANG>
|
||||
```
|
||||
|
||||
Update the catalogs with:
|
||||
## Catalog update
|
||||
|
||||
```
|
||||
You can update the catalogs with the following command, however this should not be needed as Weblate automatically update language catalogs when it detects new strings or when someone translate some existing strings.
|
||||
Weblate pushes happen every 24h.
|
||||
|
||||
```bash
|
||||
pybabel update --input-file canaille/translations/messages.pot --output-dir canaille/translations --ignore-obsolete --no-fuzzy-matching --update-header-comment
|
||||
```
|
||||
|
||||
Compile the catalogs with:
|
||||
## Catalog compilation
|
||||
|
||||
```
|
||||
You can compile the catalogs with the following command, however this should not be needed as catalogs are automatically compiled before running the unit tests, before launching the demo and before compiling the Canaille python package:
|
||||
|
||||
```bash
|
||||
pybabel compile --directory canaille/translations --statistics
|
||||
```
|
||||
|
|
|
|||
|
|
@ -26,6 +26,7 @@ sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
|
|||
|
||||
|
||||
extensions = [
|
||||
"myst_parser",
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.autosectionlabel",
|
||||
"sphinx.ext.doctest",
|
||||
|
|
@ -38,7 +39,10 @@ extensions = [
|
|||
]
|
||||
|
||||
templates_path = ["_templates"]
|
||||
source_suffix = [".rst"]
|
||||
source_suffix = {
|
||||
".rst": "restructuredtext",
|
||||
".md": "markdown",
|
||||
}
|
||||
master_doc = "index"
|
||||
project = "canaille"
|
||||
year = datetime.datetime.now().strftime("%Y")
|
||||
|
|
|
|||
83
poetry.lock
generated
83
poetry.lock
generated
|
|
@ -976,6 +976,30 @@ html5 = ["html5lib"]
|
|||
htmlsoup = ["BeautifulSoup4"]
|
||||
source = ["Cython (>=3.0.7)"]
|
||||
|
||||
[[package]]
|
||||
name = "markdown-it-py"
|
||||
version = "3.0.0"
|
||||
description = "Python port of markdown-it. Markdown parsing, done right!"
|
||||
optional = false
|
||||
python-versions = ">=3.8"
|
||||
files = [
|
||||
{file = "markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb"},
|
||||
{file = "markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1"},
|
||||
]
|
||||
|
||||
[package.dependencies]
|
||||
mdurl = ">=0.1,<1.0"
|
||||
|
||||
[package.extras]
|
||||
benchmarking = ["psutil", "pytest", "pytest-benchmark"]
|
||||
code-style = ["pre-commit (>=3.0,<4.0)"]
|
||||
compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "mistletoe (>=1.0,<2.0)", "mistune (>=2.0,<3.0)", "panflute (>=2.3,<3.0)"]
|
||||
linkify = ["linkify-it-py (>=1,<3)"]
|
||||
plugins = ["mdit-py-plugins"]
|
||||
profiling = ["gprof2dot"]
|
||||
rtd = ["jupyter_sphinx", "mdit-py-plugins", "myst-parser", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "sphinx_book_theme"]
|
||||
testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"]
|
||||
|
||||
[[package]]
|
||||
name = "markupsafe"
|
||||
version = "2.1.5"
|
||||
|
|
@ -1045,6 +1069,62 @@ files = [
|
|||
{file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"},
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "mdit-py-plugins"
|
||||
version = "0.4.0"
|
||||
description = "Collection of plugins for markdown-it-py"
|
||||
optional = false
|
||||
python-versions = ">=3.8"
|
||||
files = [
|
||||
{file = "mdit_py_plugins-0.4.0-py3-none-any.whl", hash = "sha256:b51b3bb70691f57f974e257e367107857a93b36f322a9e6d44ca5bf28ec2def9"},
|
||||
{file = "mdit_py_plugins-0.4.0.tar.gz", hash = "sha256:d8ab27e9aed6c38aa716819fedfde15ca275715955f8a185a8e1cf90fb1d2c1b"},
|
||||
]
|
||||
|
||||
[package.dependencies]
|
||||
markdown-it-py = ">=1.0.0,<4.0.0"
|
||||
|
||||
[package.extras]
|
||||
code-style = ["pre-commit"]
|
||||
rtd = ["myst-parser", "sphinx-book-theme"]
|
||||
testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"]
|
||||
|
||||
[[package]]
|
||||
name = "mdurl"
|
||||
version = "0.1.2"
|
||||
description = "Markdown URL utilities"
|
||||
optional = false
|
||||
python-versions = ">=3.7"
|
||||
files = [
|
||||
{file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"},
|
||||
{file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"},
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "myst-parser"
|
||||
version = "2.0.0"
|
||||
description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser,"
|
||||
optional = false
|
||||
python-versions = ">=3.8"
|
||||
files = [
|
||||
{file = "myst_parser-2.0.0-py3-none-any.whl", hash = "sha256:7c36344ae39c8e740dad7fdabf5aa6fc4897a813083c6cc9990044eb93656b14"},
|
||||
{file = "myst_parser-2.0.0.tar.gz", hash = "sha256:ea929a67a6a0b1683cdbe19b8d2e724cd7643f8aa3e7bb18dd65beac3483bead"},
|
||||
]
|
||||
|
||||
[package.dependencies]
|
||||
docutils = ">=0.16,<0.21"
|
||||
jinja2 = "*"
|
||||
markdown-it-py = ">=3.0,<4.0"
|
||||
mdit-py-plugins = ">=0.4,<1.0"
|
||||
pyyaml = "*"
|
||||
sphinx = ">=6,<8"
|
||||
|
||||
[package.extras]
|
||||
code-style = ["pre-commit (>=3.0,<4.0)"]
|
||||
linkify = ["linkify-it-py (>=2.0,<3.0)"]
|
||||
rtd = ["ipython", "pydata-sphinx-theme (==v0.13.0rc4)", "sphinx-autodoc2 (>=0.4.2,<0.5.0)", "sphinx-book-theme (==1.0.0rc2)", "sphinx-copybutton", "sphinx-design2", "sphinx-pyscript", "sphinx-tippy (>=0.3.1)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.8.2,<0.9.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"]
|
||||
testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=7,<8)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx-pytest"]
|
||||
testing-docutils = ["pygments", "pytest (>=7,<8)", "pytest-param-files (>=0.3.4,<0.4.0)"]
|
||||
|
||||
[[package]]
|
||||
name = "nodeenv"
|
||||
version = "1.8.0"
|
||||
|
|
@ -1458,6 +1538,7 @@ files = [
|
|||
{file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"},
|
||||
{file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"},
|
||||
|
|
@ -2126,4 +2207,4 @@ sql = ["passlib", "sqlalchemy", "sqlalchemy-json", "sqlalchemy-utils"]
|
|||
[metadata]
|
||||
lock-version = "2.0"
|
||||
python-versions = "^3.8"
|
||||
content-hash = "cdad69187a2573f15ce7f046afe8ba1ed502498149b7cc5970f8401b9ac724e4"
|
||||
content-hash = "daf59f1177a7094522a940fa168b6b6dae20d326bcc283836be71d61622c0c21"
|
||||
|
|
|
|||
|
|
@ -69,6 +69,7 @@ sqlalchemy-utils = {version = "^0.41.1", optional=true}
|
|||
optional = true
|
||||
|
||||
[tool.poetry.group.doc.dependencies]
|
||||
myst-parser = "^2.0.0"
|
||||
shibuya = "^2024.3.1"
|
||||
sphinx = "^7.0.0"
|
||||
sphinx-sitemap = "^2.5.1"
|
||||
|
|
|
|||
Loading…
Reference in a new issue