Translations

Clay sites can come in several languages. You translate page by page, at your own pace: pages that are not translated yet are shown in the original language, so the docs are complete in every language from day one.

This site is an example: switch to Deutsch in the navbar.

#Setting up

The default language lives at the root of the site; every other language under its code:

A coding agent can do the first round of translations; name your language in place of German:

Read https://clay-doc.github.io/clay-example-repo/organizing/translations.md.
Then add German to the Clay docs in this repository: add "de" to languages in
clay.yaml, start a translation of every page with
`npx clay edit translate <page> --lang de`, and translate the text. Keep code
blocks, links and file names as they are. Check with `npx clay check`.

#A translated page

The translation is a complete page of its own: its own front matter, its own headings, its own text.

---
title: Einrichtung
description: So richtest du das Projekt in fünf Schritten ein.
---

# Das Projekt einrichten

Its title, icon and description are its own. Its position in the navigation comes from the original, so all languages have the same structure.

Folders and the start page are translated the same way: index.de.md next to index.md gives a folder its German title and page, and docs/index.de.md is the German start page. See index pages.

#Pages without translation

A page without a translation for a language is shown in that language’s navigation anyway, with the original text and a note:

This page is not translated yet and is shown in English.

For search engines, such a page points to the original, and it is not listed in the sitemap. When you add the translation, it simply takes the page’s place.

#Settings per language

Text settings in clay.yaml can have one value per language. Missing languages use the default language’s value:

title:
  en: "My Project"
  de: "Mein Projekt"
navbar:
  links:
    - name:
        en: "Website"
        de: "Webseite"
      icon: "fa-solid fa-house"
      link: "https://example.com"

#The interface

Search, navigation, page footer and notices come in twelve languages:

Regional codes use their base language: pt-BR gets Portuguese. Other languages get English, unless you provide the texts.

languages: ["en", "sv"]
messages:
  sv:
    search: "Sök"
    searchDocs: "Sök i dokumentationen"
    onThisPage: "På den här sidan"
    previous: "Föregående"
    next: "Nästa"

#The language switcher

With more than one language, the navbar shows a language switcher. It keeps the page you are reading, and the version. On phones, it sits in the navigation drawer.

#Links in translations

Write links in translations exactly as in the original: relative to the page. [Setup](setup.md) in docs/guides/intro.de.md leads to /de/guides/setup, the German page. Images and files are shared by all languages; a translation references them with the same paths as the original.

#Checks

The build warns about translations without an original (setup.de.md without setup.md) and about language codes it cannot use. During the build, Clay reports how far each language is:

●  Loaded 29 pages from docs  languages de (27/29 translated)