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 language code:

great-docs.yml
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 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:

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

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 covers the language setting and other great-docs.yml options
  • Theming & Appearance explains how translated labels integrate with your site’s visual design
  • SEO Optimization covers how language settings affect search engine indexing
  • Social Cards explains Open Graph metadata, which can include language attributes