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

Generating .po files to be translated by Weblate

• 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.
• Combine all these .po files into a single file in po/_docs.po.
• Repeat, but with _posts instead of _docs.
• Delete all of the intermediate files when done.

Generating localised .md files from the translated .po files

• 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.