Update 23-internationalization.qmd

Author: rich-iannone

user_guide/23-internationalization.qmd

@@ -8,22 +8,31 @@ versions: ">=0.4"
 
 # Internationalization
 
-Great Docs can display all of its UI text in multiple languages. When you set a language, every button label, tooltip, relative timestamp, navbar link, and accessibility attribute across the site is automatically translated.
+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:
+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:
 
 ```{.yaml filename="great-docs.yml"}
 site:
   language: fr
 ```
 
-If you don't set a language, Great Docs defaults to English (`en`).
+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:
+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 |
 |------|----------|
@@ -51,9 +60,13 @@ Great Docs ships with translations for 23 languages:
 | `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:
+Setting the language affects every piece of UI text that Great Docs generates. Here's a summary of
+what changes:
 
 ### Navbar Labels
 
@@ -81,41 +94,64 @@ All interactive widgets use the configured language:
 
 ### 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.
+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.
+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
 
 ::: {.callout-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.
+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
 
-Some translation strings include placeholders and plural forms. These are handled automatically by the widgets at runtime:
+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.
+- **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:
+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
+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.
+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, search, tooltips) while you focus on translating the content that matters most.
+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.qmd) covers the `language` setting and other `great-docs.yml` options
-- [Theming & Appearance](theming.qmd) explains how translated labels integrate with your site's visual design
+- [Configuration](configuration.qmd) covers the `language` setting and other `great-docs.yml`
+options
+- [Theming & Appearance](theming.qmd) explains how translated labels integrate with your site's
+visual design
 - [SEO Optimization](seo.qmd) covers how language settings affect search engine indexing
+- [Social Cards](social-cards.qmd) explains Open Graph metadata, which can include language
+attributes