PO Translations

Documents that are typically edited and modified many times during their life-cycle should better be translated in manageable chunks using a sophisticated translation workflow with a professional toolset.

In such cases it is better to focus on the content in the main language and manage the translations with the normal translation workflow.

You will also find that necessary, when you let translations be done by external translators as they will not be very happy to edit markdown files.

As an additional benefit, the translation process is also cheaper and more efficient, even when you do the translations yourself.

Trigger Documents

The central idea of content inernationalization in Qgoda are so-called trigger documents. They have no content but only front matter:

---
master: /en/about-strawberries.md
lingua: de
title: Über Erdbeeren
---

The interesting variable here is asset.master. It just points to the same document in the main language.

The asset.lingua variable is also crucial to specify because Qgoda has to know for which language it has to pull translations. But you normally specify asset.lingua in the defaults of your _config.yaml.

All other variables that you add to the front matter are just added to the document and available as regular asset variables.

Translating Front Matter

But you don't have to manually translated the front matter from the original document. Instead you can extract the relevant parts of it to the .po file. This is done with the special variable asset.translate:

---
master: /en/about-strawberries.md
translate:
    - title
    - description
---

This has the effect that the values of the front matter variables title and description are extracted from the master document into the .po file, and their translations will be used, when generating the translated document.

You will normally always want to translate the same set of front matter variables for every document. This is normally done by specifying defaults:

defaults:
  - files:
      - /*/**
  - values:
      translate:
        - title
        - description

There is no problem specifying variables that don't appear in every one of your documents. List entries that don't exist for a particular document are simply ignored.

Missing Translations

What if a certain string has not been translated yet? The gettext way of handling that situation is to use the original string, that is the string in the main language of your site. That's not perfect but better than nothing and you can always remedy it by providing a translation.

What Else?

Nothing! It's as simple as that. Just set the defaults for asset.translate and asset.lingua in _config.yaml. And then creating a translated version of every document is as simple as:

---
master: /en/qgoda-rocks.md
---

This site itself is translated into German using exactly this technique.