Skip to content

Maintaining documentation in English and Spanish

The public docs site is built with MkDocs and supports two locales: English (default) and Spanish (Mexico). The language switcher appears in the documentation header when you build the site.

File naming

  • English (default language): use the normal filename, for example workflow/bids.md.
  • Spanish: add the .es locale suffix before .md, for example workflow/bids.es.md, in the same folder as the English page.

Every English page that ships to users should have a matching *.es.md. If a Spanish file is missing, the build can fall back to English; do not rely on that for new or updated content—update both files together.

Spanish locale and UI labels

  • Write explanatory prose in Mexican Spanish (vocabulary and spelling conventions appropriate for Mexico, not Spain).
  • Keep user interface strings exactly as they appear in the product, in English: screen names (Dashboard, Bids, Jobs), buttons (Create new, Submit, Post Update), statuses (Bid Approved, In Progress), and role names when they match the app (Owner, Project Manager, Badge Worker). Readers need to recognize the same labels they see in Hardhat Flow.

Use Spanish around those terms for grammar and clarity, for example: “En la lista de Jobs, seleccione …”.

Use relative links without locale suffixes, for example [Recording Payments](payments.md). MkDocs resolves the correct language file for the current build.

Spanish section and page titles in the sidebar are configured under plugins.i18n.languages → nav_translations for locale es in docs-site/mkdocs.yml. When you add a new nav entry in English, add the matching Spanish label there.

Build

From the repository root:

uv run mkdocs build -f docs-site/mkdocs.yml

English output is written to docs_build/; Spanish is under docs_build/es/.