Translating documentation

Contributor guide for translating OpenQuok docs into other languages — locale folders, URL paths, Markdown authoring, and pull requests.

4 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start for $0

Overview

OpenQuok documentation is Markdown-first and supports multiple languages. English is the default under web/src/content/docs/ and is served at /docs/.... Translations live in sibling folders named docs-<locale> — for example web/src/content/docs-es/ for Spanish at /docs/es/....

Readers switch languages from the language picker in the docs header. It keeps the same page slug and swaps only the locale prefix (/docs/getting-started ↔ /docs/es/getting-started).

web/src/content/
  docs/                          # English (default) → /docs/<slug>
    getting-started/
      index.md
      quickstart.md
    channels/
      connect.md
  docs-es/                       # Spanish → /docs/es/<slug>
    getting-started-for-dev/
      installation.md
    documentation-contribution/
      writing-content.md

Note

Translations do not need to cover every English page before you open a PR. Ship one section or a handful of pages — partial locale coverage is welcome as long as each added file mirrors a real English source page.

What you translate vs what stays the same

Keep in English (or unchanged)	Translate
Repo paths, env var names, CLI flags, HTTP routes, JSON keys	Headings, body copy, table labels, callout text
openquok CLI commands and code samples	LinkCard title and description
Product name OpenQuok (brand casing)	Sentences that explain concepts to readers
import paths and component names in <script> blocks	FAQ answers, step instructions, intro paragraphs
GitHub URLs and third-party doc links	Sidebar label overrides when the English title does not fit

Leave fenced bash blocks copy-pasteable — translate comments inside them only when it helps, not the commands themselves.

Contributor checklist

Pick a source page and locale

Choose an English page under web/src/content/docs/ — start with a section you know well (for example getting-started/quickstart.md or channels/connect.md).
Confirm the target locale is registered in web/src/lib/docs/constants/config.ts under docsI18n.locales. Today that includes en (English) and es (Español).

To add a new language (for example French), append a row to docsI18n.locales and create web/src/content/docs-fr/. Use a short ISO-style code (es, fr) — the folder suffix and URL segment must match.

Mirror the English file path

Copy the relative path from docs/ into docs-<locale>/:

English source	Spanish translation	URL
docs/getting-started/index.md	docs-es/getting-started/index.md	/docs/es/getting-started
docs/documentation-contribution/writing-content.md	docs-es/documentation-contribution/writing-content.md	/docs/es/documentation-contribution/writing-content

Section roots use index.md inside a folder (slug is the folder name, not index).

Write the translated Markdown

Create the file with the same frontmatter keys as English. Translate title and description; keep order aligned so sidebar order matches.

Minimal example — English introduction (docs/getting-started/index.md):

---
title: Introduction
description: OpenQuok social scheduler — volume without the headache.
order: 0
sidebar:
  label: Overview
---

Spanish counterpart (docs-es/getting-started/index.md — illustrative; add this file when you translate the page):

---
title: Introducción
description: OpenQuok, programador de redes sociales — volumen sin complicaciones.
order: 0
sidebar:
  label: Resumen
---

<script>
import { CardGrid, LinkCard } from '$lib/ui/components/docs/mdx/index.js';
</script>

OpenQuok es un **programador de redes sociales** para publicar a escala sin perder el control.
Los agentes redactan y encolan publicaciones; tú revisas y apruebas en el **calendario**
y el **tablero kanban** antes de que se publique algo.

## Elige tu camino

<CardGrid>
<LinkCard title="Inicio rápido" description="Primer canal, primera publicación y aprobación en calendario o kanban." href="/docs/es/getting-started/quickstart" />
<LinkCard title="Cloud" description="Prueba, límites del plan y facturación en la versión alojada." href="/docs/es/cloud" />
<LinkCard title="Autoalojamiento" description="Sin factura de Cloud. Instala y ejecuta OpenQuok tú mismo." href="/docs/es/installation" />
</CardGrid>

Tip

In localized pages, prefix in-site href values with /docs/<locale>/ (for Spanish, /docs/es/...). English pages omit the locale segment.

Reuse the same MDX components as English — Callout, Steps, CardGrid, LinkCard, Badge. Follow Writing content and Built-in components; inside <Callout> bodies use HTML (<strong>, <p>) instead of Markdown emphasis.

Preview locally

From the monorepo root:

pnpm --filter ./web run dev

Open the translated URL (for example http://localhost:5173/docs/es/documentation-contribution/writing-content). Use the header language picker to confirm slug parity with English.

Open a pull request

Follow Submit a pull request. In the PR description, list:

English source path(s) you translated
Locale code and new files under docs-<locale>/
Any new locale registration in docsI18n (only when adding a language)

Existing Spanish translations

The docs-es tree is the live reference for Spanish contributors:

Path	Notes
docs-es/getting-started-for-dev/	Self-hosting intro, installation, project structure (shows docs/ vs docs-es/ layout)
docs-es/documentation-contribution/	Localized authoring guides — configuration, writing content, components

Browse Escribir contenido for a full Spanish page that uses code blocks and frontmatter in context.

PR review prompts

Before opening a PR, confirm:

File path under docs-<locale>/ matches the English slug you translated.
Frontmatter includes title, description, and order where the English page has them.
In-site links use the locale prefix (/docs/es/... for Spanish).
Code, CLI, env vars, and API paths are unchanged unless the prose around them requires a translated comment.
MDX <script> imports match English when you reuse components.
You previewed the page locally at the correct /docs/<locale>/... URL.