# Internationalization

If your project has users around the world, presenting documentation in their language makes a real difference. Even when the actual content is in English, translating navigation labels, button text, and timestamps removes friction and signals that the project cares about accessibility.

Great Docs can display all of its UI text in multiple languages. When you set a language in `great-docs.yml`, every button label, tooltip, relative timestamp, navbar link, and accessibility attribute across the site is automatically translated.


# Setting the Language

Add the `language` key under `site` in your configuration file. The value is a [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language code:


    great-docs.yml


``` yaml
site:
  language: fr
```


If you don't set a language, Great Docs defaults to English (`en`). Only a single language can be active at a time.


# Supported Languages

Great Docs ships with translations for 23 languages. If yours is in the list, all you need is the `language` key in `great-docs.yml`:

| Code      | Language              |
|-----------|-----------------------|
| `en`      | English (default)     |
| `fr`      | French                |
| `de`      | German                |
| `es`      | Spanish               |
| `pt`      | Portuguese            |
| `it`      | Italian               |
| `nl`      | Dutch                 |
| `sv`      | Swedish               |
| `da`      | Danish                |
| `nb`      | Norwegian Bokmål      |
| `is`      | Icelandic             |
| `fi`      | Finnish               |
| `ja`      | Japanese              |
| `ko`      | Korean                |
| `zh-Hans` | Chinese (Simplified)  |
| `zh-Hant` | Chinese (Traditional) |
| `ru`      | Russian               |
| `pl`      | Polish                |
| `cs`      | Czech                 |
| `ro`      | Romanian              |
| `tr`      | Turkish               |
| `el`      | Greek                 |
| `hi`      | Hindi                 |

If your language isn't listed here and you'd like to contribute a translation, see the [How It Works](#how-it-works) section below for details on the translation pipeline.


# What Gets Translated

Setting the language affects every piece of UI text that Great Docs generates. Here's a summary of what changes:


## Navbar Labels

The top-level navigation links are translated automatically. For example, with `language: de`:

- **User Guide** becomes **Benutzerhandbuch**
- **Recipes** becomes **Rezepte**
- **Reference** becomes **Referenz**
- **Changelog** becomes **Änderungsprotokoll**


## Widget Text

All interactive widgets use the configured language:

- **Back-to-top button**: tooltip text
- **Copy code button**: "Copy to clipboard" / "Copied!" labels
- **Copy page menu**: all menu items and status messages
- **Dark mode toggle**: "Switch to dark mode" / "Switch to light mode" tooltips
- **Sidebar filter**: placeholder text and result counts
- **Reference switcher**: "API Reference" / "CLI Reference" labels
- **GitHub widget**: "Stars", "Forks", "Issues", "Pull Requests" labels
- **Announcement banner**: dismiss button accessibility label
- **Responsive tables**: scrollable table indicator
- **Video embed**: play button and video labels


## Page Metadata

The page metadata widget displays relative timestamps like "3 days ago" or "2 months ago". These time expressions are fully translated and support correct singular/plural forms for each language. The tooltip date format also adapts to match the configured locale.


## Table of Contents

The "On this page" heading above the right-hand table of contents is translated to match your configured language.

All of these translations are applied automatically. You don't need to provide any translation files or configure anything beyond the `language` key.


# Right-to-Left (RTL) Support

> **Note: Note**
>
> RTL layout support for languages like Arabic and Hebrew is under active development and not yet available. The underlying translations exist, but the visual layout needs further work before these languages can be officially supported.


# Placeholders and Plurals

Translation strings aren't always simple substitutions. Some include dynamic values and need to handle singular and plural forms correctly. Great Docs handles both cases automatically at runtime:

- **Placeholders** use `{name}` syntax: for example, `"Refreshed {time}"` becomes `"Actualisé {time}"` in French, where `{time}` is filled in with the relative timestamp.
- **Plurals** use a `singular|plural` pipe format: for example, `"{n} day ago|{n} days ago"` becomes `"il y a {n} jour|il y a {n} jours"` in French, with the correct form selected based on the count.


# How It Works

Understanding the translation pipeline can be helpful if you're contributing translations or debugging language issues:

1.  you set `language` in `great-docs.yml`
2.  during the build, Great Docs looks up all translation strings for that language from its internal dictionary
3.  the full translation bundle is written into `_gd_options.json`
4.  after Quarto renders each page, the post-render script injects a `<meta name="gd-i18n">` tag into the HTML `<head>` containing the JSON-encoded translations
5.  each JavaScript widget reads from this meta tag using a shared `_gdT(key, fallback)` helper function

If a translation is missing for a particular key, the English fallback is used automatically. This means partial translations are safe to ship: untranslated strings appear in English rather than as blank text or error messages.


# Next Steps

Internationalization lets you serve documentation in your users' language with a single config setting. Great Docs translates all UI chrome (navigation, buttons, tooltips, timestamps) while you focus on translating the content that matters most.

- [Configuration](configuration.md) covers the `language` setting and other `great-docs.yml` options
- [Theming & Appearance](theming.md) explains how translated labels integrate with your site's visual design
- [SEO Optimization](seo.md) covers how language settings affect search engine indexing
- [Social Cards](social-cards.md) explains Open Graph metadata, which can include language attributes