I18n documentation + news posts
Overview
Here is a French translation of the All About Descriptions, Graphics, and Screenshots documentation page. From here, you will notice:
- The language chooser shows French.
- The navigation and sidebars are French (due to !70 (merged)).
- The News sidebar has the first item translated into French.
See !70 (merged) for details on the Weblate install I'm using to test this stuff.
The process
.po
files to be translated by Weblate
Generating - For each of
_docs/*.md
:- Copy the source
.md
file - Extract the
title:
attribute from the frontmatter - Strip the remaining frontmatter
- Add a
# [TITLE]
line with the contents of the title attribute to the destination.md
file. - Use
po4a
in to extract strings into a.po
file for each resulting.md
file.
- Copy the source
- Combine all these
.po
files into a single file inpo/_docs.po
. - Repeat, but with
_posts
instead of_docs
. - Delete all of the intermediate files when done.
.md
files from the translated .po
files
Generating localised - For each of
_docs/*.md
:- Copy the source .md file
- Extract the
title:
attribute from the frontmatter - Strip the remaining frontmatter
- Add a
# [TITLE]
line with the contents of the title attribute to the destination.md
file.
So far it was exactly as it was for the original conversion into .po
files. This is because the line numbers in the .po
file need to match a .md
file. They can't match the original .md
file because we stripped off the frontmatter and added a new line to the start. Therefore, when rebuilding i18n versions we need to use the same .md
source that was
used to generate the po.
- Use
po4a
to make an i18n version of the generated.md
file. - Strip the first (
# [TITLE]
) line from this.md
file - Add back the frontmatter from the original
.md
file - Replace the
title:
from the original frontmatter with the first line that was stripped from the translated.md
file. - Add a
lang: ...
attribute to the new frontmatter. - Copy this
.md
file into an i18n'ed subdirectory of the original (e.g._docs/fr/blah.md
). - Delete all of the intermediate files when done.
The result of placing these i18n markdown files in folders the i18n'ed subdirectory is that the polygot
Jekyll plugin will now look for those files, and use them to generate internationalized versions.