Translations Overview

How do translations work?

Workflows

Creating a new file (source lang)

1. Contributor creates a branch/fork and commits a new markdown file new.md does a PR it gets approved and merged into master and deployed.
2. During that deployment there is no translated markdown file yet so a placeholder will be generated.
3. Sometime later the nightly task will run, pickup this new file and push it to transifex
4. Translators at transifex will get a notification of new files at which point they can login and translate.
5. When they complete the translation 100% then the next nightly task that runs will pick it up and
   • Create a branch from master
   • Commit translated files
   • Create a PR to master from this new branch
   • Add reviewers from baklava

Updating existing files (source lang)

1. Contributor creates a branch/fork and decides to update a existing.md. They do a PR it gets approved and merged into master and deployed.
2. During deployment if the file had a completed translation it stays as it is. If there was no translation yet then a placeholder will be created from the updated english.
3. Sometime later the nightly task will run, this will push the new file changes to transifex.
4. Translators at transifex will get a notification of updated files at which point they can login and translate.
5. When they complete the translation 100% then the next nightly task that runs will pick it up and
   • Create a branch from master
   • Commit translated files
   • Create a PR to master from this new branch
   • Add reviewers from baklava

Deleting an existing file (source lang)

1. Contributor creates a branch/fork and decides to remove a file.md as it is not in use. They do a PR it gets approved and merged into master and deployed.
2. During deployment if the file had a completed translation file a placeholder will NOT get created and if it didn't then a placeholder will still NOT be generated as there will be no english version to create it from.
3. Sometime later the nightly task will run and delete the file from transifex along with its translations if any.

Run the translation pipeline

Datadog Employees only

To run the Translation Pipeline go in the Gitlab documentation Pipeline Schedule page and Play the Nightly Build

Other Notes

What is a placeholder?

A placeholder is the english content duplicated but with a disclaimer at the top indicating that this page isn't translated yet. This avoids hugo build errors or 404's when navigating the translated site.

How do we avoid getting in a loop of translating something that came through translation pipeline?

There are a couple of things that prevent this

1. Having the translation pipeline run as a nightly task. If we had it happen on every change to master when the translated files made their way to master it would trigger translations on those again and we would get into a loop or we would need to have to have filtering logic which can be troublesome when dealing with integrations that are coming from external repos.
2. We keep source content and translated content in separate files. Its quite easy to have multiple languages in a single data file for example but that again can cause the file that comes in translated to be sent back out for translations as its shared in that way. So instead we have a file for each whether its a data file or markdown file.

How do we determine what files to send to be translated

In the root of the repo is a translate.yaml configuration file. Inside this, under sources, we specify globs of files we want to send we also specify a glob destination file name.

- src: "content/**/*.md"
  dst: "*.{lang}.md"

For example here we are saying any markdown files in content/ and its child directories. Then we specify the output to be the same filename as the incoming filename but with a lang extension in between. Lang specific files like something.fr.md will be ignored automatically or the explicit ignores in the config can handle this.

How can we alter language files?

You can change for example something.fr.md files but they will get overridden next time we merge in translations. For now they need to be also entered into transifex like a translator would so that they will come through the pipeline and changes won't be lost. We are looking at a Phase 2 to automate this next.

What if a PR to master is rejected, what happens to the translations?

Because the nightly task only runs against master only changes to master will trigger translations. So a rejected PR won't get merged into master and so no changes will be sent off for translation.

What if a Translation PR is rejected?

If a translation pull request would for example break the site if you were to merge it you can easily reject it and you will not loose files. The next time the nightly task runs the same files will still come through. The same issue may come through too so it's advised you try fix the issues before then or to alter the PR to fix it.