Translations

[wolfgangwalther]

Follow up on #375.

Background: We had a semi-finished translation for chinese in the past. However, this was in a different repo and therefore hard to keep up to date.

The "proper" way of translating a sphinx-based project, would be to set up a PO-file-based translation workflow.

Some resources:

• Sphinx docs: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
• sphinx-intl: https://github.com/sphinx-doc/sphinx-intl

Then we could connect to a web-based translation platform for contributors to work on, e.g:

• https://poeditor.com/pricing/ (free for open source, we qualify)
• https://www.transifex.com/pricing/ (free for open source, not sure if we qualify)
• others?

The idea would be to set up a basic workflow and maybe translate the index page to a few languages first. This could serve as a localized landing page and also as a proof-of-concept for the workflow.

Down the road this would then enable contributors to work on a full translation, if they want to.

[yueim]

I'll try to translate to Simplified Chinese.

https://github.com/cnyyk/postgrest-docs/blob/main/README-zh_CN.md

[yueim]

Sphinx-intl workflow is ready.

bash-5.1$ tree _build/gettext 
_build/gettext
├── admin.pot
├── api.pot
├── auth.pot
├── configuration.pot
├── ecosystem.pot
├── how-tos.pot
├── index.pot
├── install.pot
├── releases.pot
├── schema_cache.pot
├── schema_structure.pot
└── tutorials.pot

0 directories, 12 files
bash-5.1$ tree locales/zh_CN/LC_MESSAGES/
locales/zh_CN/LC_MESSAGES/
├── admin.mo
├── admin.po
├── api.mo
├── api.po
├── auth.mo
├── auth.po
├── configuration.mo
├── configuration.po
├── ecosystem.mo
├── ecosystem.po
├── how-tos.mo
├── how-tos.po
├── index.mo
├── index.po
├── install.mo
├── install.po
├── releases.mo
├── releases.po
├── schema_cache.mo
├── schema_cache.po
├── schema_structure.mo
├── schema_structure.po
├── tutorials.mo
└── tutorials.po

0 directories, 24 files
bash-5.1$ 

[yueim]

@wolfgangwalther
Hi, there's a problem:
Release notes are separated html files located in releases folder.
Should be change to rst file for translation.

[wolfgangwalther]

Release notes are separated html files located in releases folder.
Should be change to rst file for translation.

Those files are .rst for me - not .html. Not sure what you're looking at exactly?

[wolfgangwalther]

Sphinx-intl workflow is ready.

Thanks for picking this up, this is awesome.

I have not looked at things in detail, yet, but it would be great if we could wrap the tooling that is needed into a few simple nix commands (see https://github.com/PostgREST/postgrest-docs/blob/main/default.nix), that can then be run in nix-shell.

Would you like to give this a try?

[yueim]

Release notes are separated html files located in releases folder.
Should be change to rst file for translation.

Those files are .rst for me - not .html. Not sure what you're looking at exactly?

Oh, i did the check, everything is OK, sorry for the confusion.

[yueim]

Sphinx-intl workflow is ready.

Thanks for picking this up, this is awesome.

I have not looked at things in detail, yet, but it would be great if we could wrap the tooling that is needed into a few simple nix commands (see https://github.com/PostgREST/postgrest-docs/blob/main/default.nix), that can then be run in nix-shell.

Would you like to give this a try?

It's my honor to contribute to this great project.

Yes, that's true, nix is really simple.
But nix installation needs to download dependences to /nix, it's huge and slow(I'm living in Chengdu, China).
So I read the source file default.nix, line 37 ~ 46:

serve =
  pkgs.writeShellScriptBin "postgrest-docs-serve"
    ''
      set -euo pipefail

      # livereload_docs.py needs to find "sphinx-build"
      PATH=${python}/bin:$PATH

      ${python}/bin/python livereload_docs.py
    '';

postgrest-docs-serve command is just a wrapping for livereload_docs.py.
And python3.10 is installed via homebrew, so everything will also works perfectly without nix.
See https://github.com/cnyyk/postgrest-docs/blob/main/README-zh_CN.md for specific details.

Now, index.rst has been translated, and all others translation will be finished in less than 4 weeks(just a planning).

[yueim]

In brief, the Translation Workflow maybe:

1. Install the dependencies via pip or pip3.
2. Fork or sync forked repo from PostgREST/postgrest-docs to get the latest docs.
3. Generate latest version pot files: sphinx-build -b gettext . _build/gettext.
4. Update pot changes to specific language po files: sphinx-intl update -p _build/gettext -l zh_CN.
5. Fill up all messages in po files via Poedit or other tools.
6. Check everything locally: sphinx-autobuild . _build; to open http://127.0.0.1:8000.
7. Test on readthedocs.io (NOT REALLY DONE, I'LL DO THE TEST LATER).
8. Create pull request to PostgREST/postgrest-docs then wait for reviewing and merging.
9. Check on https://postgrest.org.

[wolfgangwalther]

In brief, the Translation Workflow maybe:

Thanks for the writeup!

1. Install the dependencies via `pip` or `pip3`.
2. Fork or sync forked repo from `PostgREST/postgrest-docs` to get the latest docs.
3. Generate latest version pot files: `sphinx-build -b gettext . _build/gettext`.
4. Update pot changes to specific language `po` files: `sphinx-intl update -p _build/gettext -l zh_CN`.

I added those steps to our regular build tools in #496. This will make sure that .pot files are always generated automatically and .po files are kept up2date, too.

6. Check everything locally: `sphinx-autobuild . _build;` to open `http://127.0.0.1:8000`.

I added support for translations to the livereload script in #496. Should work with and without nix.

7. Test on readthedocs.io (NOT REALLY DONE, I'LL DO THE TEST LATER).

I set up a test project for it and will test building in #496, too.

8. Create pull request to `PostgREST/postgrest-docs` then wait for reviewing and merging.
9. Check on https://postgrest.org.

Looking forward to it! :)

[wolfgangwalther]

The tooling is done, once somebody comes up with an actual translation they can open a PR in the main repo.