{"schemaVersion":1,"title":"Versions and localization","url":"https://appgram.github.io/docsy/guides/tutorials/versions-and-locales","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/tutorials/versions-and-locales","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/tutorials/versions-and-locales.json","version":"current","locale":"en","markdown":"# Versions and localization\n\nConfigure versioned articles, translated navigation, language fallbacks, and version-specific ingestion.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy can publish multiple documentation versions and languages from one repository. The default version/language retains existing URLs; non-default combinations use `/versions/{version}/{locale}` after `site.basePath`.\n\n## Try it in this portal\n\nUse the **Version** and **Language** selectors above the article. This portal has **Current** and **Preview (demo)** versions, with **English**, **Français**, and **Español** locales.\n\n* Switch to Français or Español to see the translated overview, navigation, getting-started guide, rich-components guide, and this tutorial.\n* Open **Get started** and switch to Preview (demo) to see a different article body in either language. Preview is demonstration content, not a released Docsy version.\n* Open **YAML configuration** in French or Spanish to test the English fallback notice. Other untranslated guides are deliberately left in English.\n* Search for **testing workspace** in Preview / English, **espace de test** in Preview / Français, or **espacio de pruebas** in Preview / Español. Results and exports follow the selected context.\n\nThese examples are configured only in Docsy’s own portal. Generated projects still start with one version and their default language.\n\n## Configure versions and languages\n\n```yaml\nversions:\n  default: current\n  items:\n    - id: current\n      label: Current\n    - id: v1\n      label: Version 1\n      status: deprecated\n\nlocalization:\n  defaultLocale: en\n  fallback: true\n  locales:\n    - code: en\n      label: English\n    - code: fr\n      label: Français\n    - code: ar\n      label: العربية\n      dir: rtl\n  messages:\n    fr:\n      guides: Guides\n      version: Version\n      language: Langue\n      searchLabel: Rechercher\n      searchPlaceholder: Rechercher dans la documentation\n      onThisPage: Sur cette page\n      previous: Précédent\n      next: Suivant\n      fallback: Cette page est disponible dans la langue par défaut.\n```\n\nThe version and language selectors appear when more than one option is configured. Switching keeps the current page where it exists; otherwise it opens that context's overview. `status` accepts `current`, `beta`, or `deprecated`; non-current statuses display a notice. `dir: rtl` sets the document direction for right-to-left locales.\n\n## Register article variants\n\n```yaml\ncontent:\n  articles:\n    - slug: getting-started\n      source: content/en/getting-started.md\n      title: Getting started\n    - slug: getting-started\n      locale: fr\n      source: content/fr/getting-started.md\n      title: Bien démarrer\n    - slug: getting-started\n      version: v1\n      locale: en\n      source: content/v1/en/getting-started.md\n      title: Getting started with version 1\n    - slug: getting-started\n      version: v1\n      locale: fr\n      source: content/v1/fr/getting-started.md\n      title: Bien démarrer avec la version 1\n```\n\nOmitting `version` makes an article shared across versions. Omitting `locale` means the default locale. Registrations must have unique slug/version/locale combinations.\n\nFor each slug, Docsy first selects version-specific registrations, or shared registrations when none exist for that version. It then selects the requested locale, or the default-locale registration when `fallback: true`. It never substitutes a different version's specific article. Fallback content displays a notice; `fallback: false` omits missing translations and removes their sidebar links.\n\nWith `site.basePath: /docs`, the example produces:\n\n| Context | URL |\n| --- | --- |\n| Current / English | `/docs/guides/getting-started` |\n| Current / French | `/docs/versions/current/fr/guides/getting-started` |\n| Version 1 / English | `/docs/versions/v1/en/guides/getting-started` |\n| Version 1 / French | `/docs/versions/v1/fr/guides/getting-started` |\n\n## Translate navigation and overview copy\n\n```yaml\nnavigation:\n  - title: Guides\n    titles:\n      fr: Guides\n    items:\n      - title: Getting started\n        titles:\n          fr: Bien démarrer\n        href: /guides/getting-started\n\nhome:\n  translations:\n    fr:\n      title: Documentation pour les humains et les agents\n      description: Guides et références de votre produit.\n      eyebrow: DOCUMENTATION\n```\n\nArticle titles/descriptions come from their locale registration. UI messages fall back to English when not supplied. The translation keys are listed in `src/lib/messages.ts`; original header copy can be overridden with `searchLabel`, `searchPlaceholder`, and `llmLabel` message keys. Translation is authored by your team or coding agent; Docsy does not send content to a translation service.\n\n## Version API and SDK sources\n\n```yaml\ningestion:\n  openapi:\n    source: sources/current-api.yaml\n    versions:\n      v1: sources/v1-api.yaml\n```\n\nSDK entries support the same `versions` map for their metadata source. Versions without an override use the main source. API sections and SDK metadata are shared across locales unless their upstream content already supplies translated prose.\n\nSearch, Markdown, discovery files, JSON documents, and runtime queries use the selected context. Permission rules on canonical paths apply to all contexts; more specific variant rules can be placed earlier in the ordered rule list.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/versions-and-locales.md"}