Localization

by Dan Rigdon-Bel and Scott Davidson (Last updated: Thursday, June 17, 2021)

Source Organization

The source files that require translation are are split into up into the following categories:

1. Markdown strings
2. Configuration strings
3. Theme strings
4. Data strings

Markdown Strings

The majority of the content of the site is in the /content folder.

/content
        /cn
        /cs
        /de
        /en
        /es
        ...

These content folders contain markdown (*.md) files that get processed by Hugo (the site engine) and turned into html.

Within markdown files themselves, there are two types of string:

1. Frontmatter strings
2. Content strings

Frontmatter

Frontmatter in the file is specified by a start and ending +++. Frontmatter is the meta-data for the document. Some of that data is used for dynamic information on the page itself and other frontmatter is used to organize the site. It is important that frontmatter is localized consistently.

Frontmatter has a two parts, a key = and a "value". For example:

title = "Modeling a Rubber Duck"

The key = in this case is title and the value is Modeling a Rubber Duck/

Values in frontmatter can always be translated. Be careful not to localize the quotes (' or ") in the front matter. These should be left as the English quotes.

Key names cannot always be translated. Certain keys are used as dynamic content in a page itself. It is best to presume that a key name should not be translated.

Keys that should NOT be translated are:

---
title:
description:
authors:
thumbnail:
draft:
weight:
...
---

Key names that can be translated are used to organize the documents into taxonomies:

---
categories:
products:
disciplines:
tasks:
levels:
tags:
---

Key names are always lower case and always plural.

Be consistent with key names and values. Always use the exact same word and spelling for any frontmatter throughout the site.

Content

The strings below the final --- of the frontmatter is the content of the page.

Most standard markdown can be translated. Within markdown there can be codes that cannot be translated.

For instance HTML codes can be typed into markdown. Like other HTML code visible parts of the HTML code should be translated.

Image links locations may re-targeted to a localized version, but generally should use the default location for the resource if needed.

Also, codes such as {{< youtube z2K2LTjDdPg >}} surrounded by {{}} should NOT be translated. These are called shortcodes. See the Theme Strings section below for more information.

Configuration Strings

There is a location for site level configuration which contains some localizable strings that apply to the entire site.

In the root of the website source is the config.toml file. This controls how Hugo builds the site and site-level defaults. Each language has a section:

[languages]
  [languages.en]
    title = "Rhinoceros - Modeling Tools for Designers"
    description = "Rhino is a 3D modeler used to create, ..."
    author = "Robert McNeel & Associates"
    weight = 1
    languageName = "English"
    contentDir = "content/en"
    [languages.en.params]
      imagesDir = "images"
      docLang = "en-us" # the language code used on docs.mcneel.com
    [languages.en.taxonomies]
      "tag" = "tags"
      "category" = "categories"
      "platform" = "platforms"
      "task" = "tasks"
      "level" = "levels"
  [languages.es]
    title = "Rhinoceros - Modeling Tools for Designers!"
    description = "Rhino is a 3D modeler used to create, ..."
    author = "Robert McNeel & Associates"
    weight = 2
    languageName="Español"
    contentDir = "content/es"
    [languages.es.params]
      imagesDir = "images"
      linkedin = "https://linkedin.com/es/whoever"
      [languages.es.params.navigation]
        help = "Aide"
      [languages.es.taxonomies]
        "etiqueta" = "etiquetas"
        "categoría" = "categorías"
        "plataforma" = "plataformas"
        "producto" = "productos"
        "disciplina" = "disciplinas"
        "task" = "tareas"
        "nivel" = "niveles"
    [languages.ko]
    title = "Rhinoceros - 디자이너를 위한 모델링 도구"
    weight = 3
    languageName="한국어"
    contentDir = "content/ko"
    [languages.ko.params]
      rhinoURL = "https://www.rhino3d.com/ko"
      imagesDir = "images"
      linkedin = "https://linkedin.com/es/whoever"
      [languages.ko.params.navigation]
        help = "Aide"
      [languages.ko.taxonomies]
        "태그" = "태그"
        "카테고리"="카테고리"
        "플랫폼" = "플랫폼"
        "제품" = "제품"
        "분야" = "분야"
        "작업" = "작업"
        "레벨" = "레벨"

To configure a new language to build, another section must be added.

Special care has to be taken in the taxonomies section. The taxonomy terms on both sides of the = should be translated. The left term is the singular form of the taxonomy and the right side the the plural version of the taxonomy. The plural version of the taxonomy must match the Key names in the front matter of the markdown files.

Once the config.toml is edited and the contents of the new language folder is populated, Hugo will build the new language.

Menus

In language-specific sections of the config.toml file, there are entries that look like this:

These represent the menus that span across the top of the navigation bar as well is in the mobile-friendly menu.

In nearly all cases, it is only appropriate to translate the value of the name field. For example:

(In some select edge-cases, the url will need to be specific to the language. For example, if there is a translated Discourse site - as is the case in Italian and Chinese - that particular menu entry will need a specific url.)

Theme Strings

Hugo uses a layout system to apply templates to a specific page. Sometimes, these templates contain strings. A good example is the “New in 7” to the right of the title found in the SubD page. These strings are contained in language-specific files in themes/rhino3d.com-theme/i18n/ folder.

Please translate only the values of the other = "some string". For example, the themes/rhino3d.com-theme/i18n/en.toml entry:

[Name]
other = "Name"

might be translated to themes/rhino3d.com-theme/i18n/fr.toml as:

[Name]
other = "Nom"

The value in the [ brackets ] is the string look-up key and should NOT be translated.

(If you have a question about context, please ask. We can disambiguate context as needed.)

A few select strings in these files will include variables. For example:

[NEW-in-Vx]
other = "New in {{ .Params.included_in.since }}"

Feel free to reposition these variables as appropriate to your language. DO NOT TRANSLATE the variable itself.

Data Strings

Data files - such as data/formats/en/formats.yml - contain some strings that will need translation. Each language has a specific somedata.yml file that should be translated in order for the data values to be localized.

An example of where data might need to be translated is the Supported File Formats page. This page is generated from the data/formats//formats.yml files and it is likely that the name: and whats_new.in_v7: fields will require translation.

Is It Ready to Translate?

Localization Status lists pages that are newly available for translation, and for pages that have been changed since you last translated them.

How it works:

Localization Status checks several things, so that you don’t have to:

1. Is the English page a draft? If it is, you don’t need to deal with it.
2. Is the English page in the state Complete? If not, it probably hasn’t been fully written or edited for content and grammar in English yet. You don’t need to deal with things that aren’t complete! (You can see the state of pages in the Administration TODO list)
3. Have you already translated it? If your translation is newer than the English version, you won’t be asked to deal with it again. So, if you commit your file after the English version is committed, it counts as translated. Even if it isn’t. So only commit translations that you’re happy with.

Preview On Your Computer

You can preview the site on your computer before you commit strings.

Follow the directions in the Edit on your computer section of the Contributing guide.

Once you are set up and building the site using those instructions, to preview all languages, you will need to run the:

hugo server -e production

command to build all languages.

Once they are serving, you can navigate to your language at http://localhost:1313/fr/ (for example) in your browser.

TRADOS Notes

When using Trados Studio use the Trados markdown configuration.

Edit this page

Edit on GitHub

History

Admin