Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
335 lines (269 sloc) 9 KB
title description navTitleId topicTitle showTOC showEdit categories navCategory showTranslate order
Internationalization
Learn how to use internationalization strings in <fix>CMintS</fix> project. Usage of i18n strings, learn about translation files structure and start creating multilanguage websites.
nav-doc-title-overview
nav-doc-title-i18n
true
documentation/i18n/index.md
documentation
i18n
documentation
156
0

{i18n-p1[Paragraph in 'internationalization' section] Internationalization is one of the core features of CMintS. The idea behind is to use common structure and syntax in content pages, themes and provide additional helpers for multilanguage website management. }

{locales-dir-structure[Page heading] Locales directory structure}

{locales-dir-structure-p[Paragraph in 'Locales directory structure' section] Locale files should be located in the locales directory: }

locales
├── de
│   ├── about.json
│   └── news.json
├── en
│   ├── about.json
│   ├── header.json
│   └── news.json
└── ru
    ├── about
    │   └── team.json
    ├── about.json
    ├── documentation
    │   ├── getting-started
    │   │   └── configuration.json
    │   └── i18n
    │       └── index.json
    ├── header.json
    ├── index.json
    └── news.json

{locales-dir-structure-p2[Paragraph in 'Locales directory structure' section] Top level directories in the locales are the locale codes. Actual directory structure reflects the page path, so for example translations for the about/teams.md page translations should be located in /de/about/teams.json file to be accessible through /de/about/teams website path. }

{default-locale[Page heading] Default locale}

{default-locale-p[Paragraph in 'Default locale' section] Before strating to use i18n features user needs to also specify default locale which will be used as the source language. In order to do that, defaultLocale needs to be added to i18n options in the config.js: }

const i18nOptions = {
  defaultLocale: "en"
};

module.exports = {i18nOptions};

{locale-file[Page heading] Locale file}

{locale-file-p[Paragraph in 'Locale file' section] Locale files hold list of the translations strings, the translation strings consist of stringid, message and optional description. }

{
  "heading-main": {
    "description": "Heading of the main page",
    "message": "Заголовок"
  },
  ...
}

{translation-strings[Page heading] Translation strings}

{translation-strings-p[Paragraph in 'Translation strings' section] The translation strings can be defined in the source files by placing them inside of opening and closing curly braces. Translation string consist of stringId, optional description and source text: }

\{stringId[Description] Source text\}

{translation-strings-p2[Paragraph in 'Translation strings' section] So for example considering the ru locale in Locale file and translation string below: }

\{heading-main[Heading of the main page] Heading\}

{translation-strings-p3[Paragraph in 'Translation strings' section] Will be converted to Heading for the source(default) locale and to Заголовок for the russian locale. }

{defining-path[Page heading] Defining the path}

{defining-path-p[Paragraph in 'Defining the path' section] In order to use translation string from a specific path rather than defining source text in the page content, it's possible to define the file path next to the stringID: }

{menu-item-about(menu/header)}

{defining-path-p2[Paragraph in 'Defining the path' section] The expression above means - use string with the ID menu-item-about from the %locale%/menu/header.json files: }

/* /en/menu/header.json */
{
  "menu-item-about": {
    "description": "Menu item label",
    "message": "about us"
  }
}
/* /ru/menu/header.json */
{
  "menu-item-about": {
    "description": "Menu item label",
    "message": "о нас"
  }
}
// Translation expression
{menu-item-about(menu/header)}

{defining-path-p3[Paragraph in 'Defining the path' section] Considering the en and ru locales above, the translation expression will be converted to about us for the en locale and to the о нас for the ru locale. }

{using-tags[Page heading] Using tags}

{using-tags-p[Paragraph in 'Using tags' section] Current tags a, img, p, span, div, em, i, b, strong can be used by default in the translation strings, ex: }

\{stringId[Description] My awesome <em>source text</em> goes here\}

<a&gt;

{a-tag-p4[Paragraph in ' tag' section] When a relative URL is used with starting / path locale and hreflang attributes are being generated automatically depending on the target page language regardless whether <a> tag is declared inside or outside of a translation string. root configuration can be used for specifing root directory for the website if needed. }

{a-tag-p[Paragraph in ' tag' section] Order of the links inside of the translaton strings can be different depending on the language, for that reason the order in the locale file string need to be defined, so considering the translation string below: }

\{paragraph-1 This is <a href="https://www.example1.com">first link</a>, <a href="/random1">second link</a> and <a href="/random2">third link</a>\}

{a-tag-p2[Paragraph in ' tag' section] And Locale file with the translation string: }

{
 "paragraph-1": {
   "description": "Paragraph with several links",
   "message": "Это <a2>вторая ссылка</a2>, <a1>первая</a1> и <a3>третья ссылка</a3>"
 },
 ...
}

{a-tag-p3[Paragraph in ' tag' section] The result will be the one below: }

Это <a href="/en/random1" hreflang="en">вторая ссылка</a>, <a href="https://www.example1.com">первая</a> и <a href="/en/random2" hreflang="en">третья ссылка</a>

<fix&gt;

{fix-tag-p[Paragraph in 'fix tag' section] Some words do not suppose to be translated in the website(ex: brand names), for that reason <fix> tag can be used: }

\{fixed-id <fix>CMintS</fix> uses <fix>fix</fix> tag\}

{fix-tag-p2[Paragraph in 'fix tag' section] and the locales below: }

"fixed-id": {
 "message": "<fix2> тэг используется <fix1>-ом"
}

{fix-tag-p3[Paragraph in 'fix tag' section] Will result into: }

fix тэг используется CMintS-ом

<img&gt;

{img-tag-p[Paragraph in ' tag' section] Similar to the <a> and <fix> tags <img> tag also should keep it's order in the translation strings, so for: }

\{test-img1 This is <img href="/first.png"> and <img href="/second.png"> image\}

{img-tag-p2[Paragraph in ' tag' section] and the locales below: }

"test-img1": {
   "description": "Test images order",
   "message": "Это <img2> картинка и <img1>"
}

{img-tag-p3[Paragraph in ' tag' section] will result into: }

Это <img href="/second.png"> картинка и <img href="/first.png">

{title-alt-attr[Page heading] title and alt attributes}

{title-alt-attr-p[Paragraph in 'title and alt attributes' section] Some attributes are also suppose to be translated in different languages, so that attributes can also be used in the translation string tags: }

\{test-attribute1 <div title="Website Logo" id="logo"><img src="/random/path" alt="Jumping puma" />Picture</div>\}

{title-alt-attr-p2[Paragraph in 'title and alt attributes' section] and the locales below: }

"test-img1": {
   "description": "Test images order",
   "message": "<div1 title='Логотип сайта'><img1 alt='Пума в прыжке'>Картинка</div1>"
}

{title-alt-attr-p3[Paragraph in 'title and alt attributes' section] will result into: }

<div title="Логотип сайта" id="logo"><img src="/random/path" alt="Пума в прыжке" />Картинка</div>

prefix, postfix

{prefix-postfix-p1[Paragraph in 'prefix, postfix' section] It's also possible to specify custom prefix and postfix for i18n strings in the config.js, it can be useful for fixing incompatibilities with other syntaxes: }

{consider(common)}

/* config.js */

const i18nOptions = {
  defaultLocale: "en",
  prefix: "{{",
  postfix: "}}"
};

module.exports = {i18nOptions};

{prefix-postfix-p2[Paragraph in 'prefix, postfix' section] For the configuration specified above, you could use the syntax below: }

\{\{stringId[Description] Source text\}\}
You can’t perform that action at this time.