Tooling for translations

[wolfgangwalther]

As #393 recently got some traction, I'm adding support for translations to our build tools.

The main features are:

• postgrest-docs-build will now update .po files' msgids automatically.
• postgrest-docs-build and postgrest-docs-serve can take an argument to build/serve in a specific language

@cnyyk could you test the livereload_docs.py script? It should work without nix, too. Just call it like ./livereload_docs.py zh_CN.

I also moved all the actual docs files to a docs/ subfolder to separate the tooling from the content a little bit more.

TODO:

• Add CI check to confirm that all changes to .po files have been committed. Will do after ci: switch to GitHub Actions #495 is done.
• Support postgrest-docs-spellcheck for other locales. Edit: aspell does not support Chinese: http://aspell.net/0.60.7/man-html/Unsupported.html. We might add it later for other languages, once there is a need.

Each translation/locale needs another readthedocs project, which will then be set as a "translation project" in their settings. I created a project for simplified chinese as that's currently worked on. @steve-chavez I added you to the project on readthedocs, too - could you please setup the integration / sync the webhook (I'm missing permissions), so that we can test the build process. I'd like to know how PRs are built once we have a translation. I hope to have builds for both languages at the same time.

[steve-chavez]

could you please setup the integration / sync the webhook (I'm missing permissions), so that we can test the build process

Sure, I've just hit the resync button. I think it worked because the integration page now shows a 200 activity.

[wolfgangwalther]

Sweet - it's building both the english and the chinese version for each PR now.

Not quite perfect with the naming, yet:

docs/readthedocs.org:postgrest — Read the Docs build succeeded!
docs/readthedocs.org:postgrest-docs — Read the Docs build succeeded!

Not sure where we can change that. The second one definitely seems to be built in Chinese, though :)

[wolfgangwalther]

Not sure where we can change that. The second one definitely seems to be built in Chinese, though :)

Turns out I had to recreate the project on readthedocs to change the "project slug". @steve-chavez could you do me a favor and sync the webhook in the newly created project once more?

That should then display it in PRs as postgrest-zh-cn instead of postgrest-docs.

[steve-chavez]

could you do me a favor and sync the webhook in the newly created project once more?

Done! Got another 200.

[wolfgangwalther]

Ok, that works. Should be good to merge, but I'll keep this open until @cnyyk has maybe tested it a bit, too, and has something to put in a PR. No need to carry the empty set of .po files in the meantime.

[haowuge]

Hello, is there any progress on the Chinese translation project?
I think there seems to be a pause?

[steve-chavez]

Looks like @cnyyk is inactive now. @haowuge Would you like to maintain the chinese docs?

I don't recall the procedure here. Maybe Wolfgang can give you more details.

[haowuge]

@steve-chavez Hello steve-chavez , my English is not very good, I tried to translate, but the effect is not satisfactory

[yueim]

Hi, @wolfgangwalther @steve-chavez @haowuge,

COVID-19 made things chaos,
I hope we can get the Simplified Chinese translation released in 2023 (3 months left).

Here's a progress brief (unitl 2023-03-27):

File	Progress
admin.po	7%
api.po	54%
auth.po	5%
configuration.po	3%
ecosystem.po	100%
how-tos.po	97%
index.po	100%
install.po	5%
releases.po	99%
schema_cache.po	48%
schema_structure.po	99%
tutorials.po	96%

And there're 4 thinngs need to be done:

1. Sync po files with latest .rst files
2. Do the translation
3. Test on readthedocs.org
4. PR to postgrest-docs

Working Repo:
https://github.com/yueim/postgrest-docs

[yueim]

Here's the old deadline.

I'll make an new plan for this work.

[wolfgangwalther]

Because of PostgREST/postgrest#2814, I rebased this PR on latest main, fixed the tooling with new nixpkgs. I will merge this without the empty locale files for zh_CN, which only served as an example.

If the tooling needs any improvements, we can work on those later. Just want to get PRs closed here now.