Translating content¶

TODO: intro copy

Getting started with translating¶

To get started, you need let us know you're interested in translating so we can add you to the Weblate translation team. The first step is ensure you have an account on Weblate. Create a new account if you don't currently have one.

There are two options for letting us know that you'd like to help out with translations:

If you're on Discord, join the BeeWare server, and head to the #translations channel.
If you're not on Discord, you can create a new issue on the BeeWare Docs Tools repository.

In both cases, leave a message including the following information:

Your Weblate username
The language you are planning to which you are planning to translate content

Once we have this info, we'll get you added to the team.

New translations¶

If the language you plan to help out with doesn't already exist, there is some setup necessary on our end before you can get started.

To set up a new language, the following steps must be completed:

Create the /docs/mkdocs.language-code.yml file, with language-specific content.
Update tox.ini to include the new language build commands.
Update /docs/config.yml to include the language under extra: alternate:.

The following demonstrates the necessary changes using German as an example.

The new MkDocs configuration file¶

The first thing to do would be to create a new file named mkdocs.de.yml in the docs directory, with the following content:

INHERIT: config.yml
site_name: BeeWare Demo zu Docs Tools
site_url: https://beeware-docs-tools.beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Here's what is going on in this file:

This file inherits the configuration content from config.yml.
The site_name value is translated.
The site_url value is the project site URL, followed by the language code.
The docs_dir should be the language code.
The theme: language: value should be the language code, as specified by the MkDocs Material theme. The list can be found here. For most languages, this will be the same as the docs_dir language code; but for some (in particular languages with locale variants like zh_CN), there are differences.
The extra: translation_type: should be machine until the translation reaches 100% for the first time, at which point it should be human. It will revert to machine from human if it regresses to below 90%.

The update to `tox.ini`¶

You'll need to make several changes to the tox.ini file.

You would add the following:

The new language code environment flag to the header line which begins [testenv:docs, with the language code preceded by a -, with no spaces included, e.g. -de.
The new language code exclusion to the first command, which begins with !lint, preceded by -!, with no spaces included, e.g. -!de.
The new language code to the end of the line beginning with translate : build_po_translations.
The new language code to the end of the line beginning with translate : update_machine_translations
A new command, beginning with, for example, de : build_md_translations for German, after the other existing language-specific commands that matches the content those commands with the new language code.
The new language code to the end of the line beginning with all,serve :.

The update to `config.yml`¶

You need to add the language to config.yml for it to show up in the language selector in the header. Find the section beginning with extra:, and then locate the subsection beginning with alternate:. For German, you would add the following:

    - name: Deutsch
      link: /de/
      lang: de

The language name should be translated into the language. The link must include the /s.

The new language is now ready to begin translation.

Translation guidelines¶

Once you've been added to the team, it's time to log into Weblate and begin working through translating strings.

Tone versus word-for-word translation¶

It's more important to maintain the tone of the English text than to strive for a word-for-word translation. We try to be friendly and a bit colloquial in our content; try to maintain the spirit of that in your translations.

If the English text contains a strong English idiom, don't feel beholden to maintain the idiom, if there is an analog in your language that would work equally well. If the term or phrase in the English text is a particularly idiomatic or slang term, don't be afraid to tell us we should consider making a change. Even for English speakers, idioms and slang can pose difficulty. Sometimes we need to change the English text to make it more straightforward for translators and readers alike.

Should I translate it?¶

Die folgenden Punkte sollten nicht übersetzt oder aktualisiert werden:

Befehle. Zum Beispiel sollte in "You should run `briefcase create`." nur "You should run" übersetzt werden.
Namespaces; class, method, or attribute names.
Link URLs. Standard Markdown links should appear in Weblate as [Link text]{1}, where 1 is the position of the link in the string with reference to other possible links. If the full URL is included in the string, as [Link text](https://example.com), the URL should be skipped for translation.
Reference links containing class, method or attribute names. These should be left as-is, including the backticks. Every part of the example link shown here would not be translated.
```
[`Class.attribute`][Class.attribute]
```
Reference link link-content. For example, link-content would be skipped in the following: [Link text][link-content].
Jinja directives. This is any content wrapped inside two pairs of matching curly braces, or a matching pair of single curly braces with percent signs inside each end. Note: Including an example of the syntax here causes the Macros plugin to attempt to render it; see the Macros documentation for examples.
Custom anchors. They are found after headers or above some content, and are formatted as { #anchor }.
Admonition syntax. As shown here, the word "admonition" should not be translated. This goes for all styles of admonitions, including notes, warnings, etc. See the next section for information on translating the rest of the content.
```
/// admonition | Title

Content.

///
```
Backticks. They are meant to stay as backticks; they are used for formatting both inline code and code blocks.
Die Syntax für die Einbeziehung externer Inhalte. Dies ist alles, was in derselben Zeile wie -8<- oder in den Zeilen zwischen zwei -8<- in getrennten Zeilen steht.

Die folgenden Punkte sollten übersetzt werden:

Link text. In link syntax, the text comes before the URL, and is enclosed in brackets, as in [Link text](URL). Standard Markdown links should appear in Weblate as [Link text]{1}, where 1 is the position of the link in the string with reference to other possible links.
Reference link text. For example, Link text would be translated in the following: [Link text][link-content].
Titel und Inhalt der Ermahnung. Wie unten dargestellt, sollten "Titel" und "Inhalt" übersetzt werden. Siehe oben für Informationen über die Syntax.
```
/// admonition | Title

Content.

///
```

Weblate¶

Weblate processes everything on a string-by-string basis. It batches changes, and every couple of hours, it will submit a bulk commit with all the strings that have changed in that interval. So, it may take a couple of hours for your changes to show up on the website, but you can expect the update to appear within four hours.

If after that time, your changes still haven't appeared, the likely cause is a markup error, resulting in a failure in the docs build for that language. Any markup problem in any string will block the entire translation from being public. You can keep an eye on the build page for your language to see whether it has successfully built. The link is formatted similarly to this link to the French build page https://app.readthedocs.org/projects/beeware-docs-tools-fr/; change the language code to your language to view the appropriate build page. This will show the state of the most recent build of the site. If the build fails, look at the build log, and see if you can identify the source of the problem.