Add Spanish translation of the docs by lmac-1 · Pull Request #902 · OpenFn/docs

lmac-1 · 2026-10-02T14:35:19Z

Short Description

#884 should merge before merging this PR (which contains the actual Spanish content and rules)

Turns on Spanish for the docs site, with a language dropdown in the navbar, and adds the skills and rule files used to translate and review it.

Details

Site changes:

docusaurus.config.js: adds the es locale, a localeDropdown in the navbar, and editLocalizedFiles so "Edit this page" opens the translated file.
docusaurus.config.js: removes the unused tagline; the homepage subtitle is now a translatable string in index.js.
src/pages/index.js: the homepage text can now be translated, and homepage links stay in the reader's language.
sidebars-adaptors.js: gives each adaptor sidebar item a unique translation key. Without it, building any non-English locale fails with "Multiple docs sidebar items produce the same translation key".
Spanish pages and interface text (via Translate docs into Spanish using our /translate skill #884). All are machine translations, not yet human-reviewed. Untranslated pages fall back to English with a notice.

Tooling and rules:

New skills: translate (pages and interface text) and review-translation, with check-translation.js to flag glossary terms and rule breaks in translated pages.
glossary.yml: terms can now list a word for a locale (Spanish translates project, credential, collection and operation).
translation-rules.yml and a house style guide per locale (es.md).
AGENTS.md and README.md updated, including how to run the site in Spanish locally.

Small English fix: docs/get-started/terminology.md now says the Input and Output are the initial and final state.

Follow-up after deploy: Spanish search returns no results until the Algolia crawler is set up to index /es/ pages.

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to know!):

I have used Claude Code
I have used another model
I have not used AI

You can read more details in our Responsible AI Policy

Wrap the homepage copy in Translate so it can be extracted, give generated adaptor sidebar items unique keys so a second locale can build, and declare the i18n config with English as the only locale. Nothing changes for readers.

The highlight cards used a plain <a href> with a relative path, which dropped the locale prefix. Use Link with an absolute path so baseUrl, including /es/, is applied.

It generates the adaptor sidebar and now carries the keys that let a second locale build, so an edit there can break translated builds without touching English.

Prepare the site for translation

Build the es locale at /es/ so the translate skill can run against it, but keep the language dropdown out of the navbar until Spanish is ready for readers.

The callout on the terminology page ended with `:::note` instead of `:::`.

"initial state" and "final state" read as ordinary words, so translations turned them into ordinary words too. Formatting them as `state` makes it clear they name the object, which glossary.yml keeps in English.

SKILL.md keeps the shared rules and points to pages.md (translate a set of pages) or interface.md (the navbar, footer, sidebar headings and homepage). interface.md is new: it says which write-translations output to keep and which to remove. The skill no longer names French; it translates into whichever locales are enabled.

Remove only theme.* from code.json so new custom strings are not deleted. Show the do-not-retranslate example as Prettier leaves it, and run Prettier on the skill files and AGENTS.md.

Split the translate skill into pages and interface tasks

These files hold only the section titles and sidebar heading, not the posts, so they are translated like the rest of the interface.

They now have a Spanish translation pinned under locales.

# Conflicts: # .agents/skills/translate/SKILL.md

The translate skill now keeps the translation of every block whose English has not changed, and checks glossary terms block by block.

side-by-side.js --json now gives each changed block a previous field with the old English, its old translation and a word diff, so the translator can tell a typo fix from a change in meaning. pages.md says how to use it, and that the source hash is updated even when no translated text changes.

Move the Spanish register and gender rules from translation-rules.yml into .agents/skills/translate/es.md, and add rules from the Get Started review: Spanish capitalization, straight quotes, "por ejemplo" instead of "p. ej.", and more es-419 word choices. translation-rules.yml now holds only single-phrase fixes from review. The skill also asks for natural rather than word-for-word phrasing, and retranslates machine pages when the house style changes.

The English says "Key Outputs", not "deliverables", so the rule never matched and "Resultados clave" was already right.

The previous commit deleted one line too early.

A change to the glossary, the rules, or a locale's house style used to retranslate every machine page in full, which rewords every block and buries what the rule changed. Now only the text that breaks a new rule is fixed. Deleting a page still gives a fresh translation when that is wanted.

Checks translated pages against the English in a fresh session, after /translate pages: searches for house style rule breaks, reads each block for changed meaning and literal phrasing, fixes what is clear, and reports the rest. It also says what marking a page human-reviewed involves. Also formats the "When the rules change" section of pages.md, which missed Prettier.

# Conflicts: # .agents/skills/translate/SKILL.md

- side-by-side.js: remove the HTML output and --base. --check now also catches English -ed/-ing forms and stops matching "mejor" for "mejorar". - pages.md: cut repetition; fenced blocks in one place; check list ends with build, commit, /review-translation. - review-translation: report by page URL and section heading, with the English, before, and after in full. - Glossary terms marked translate: true use the word for the locale, and the skill stops if a locale has none. glossary.yml points to STYLE.md.

Every glossary term is translate: false again. A term's locales entry (es: proyecto) overrides the English for that locale only, so a new locale keeps the English until someone adds a word for it.

… script Drop side-by-side.js --json: it lost translations for repeated blocks and missed moved ones. Updates now edit the translation in place from a word diff of the English. --check skips rules missing source or target, and no longer flags terms the locale translates under locales. Heading anchors now come from docusaurus write-heading-ids, which skips code blocks and strips links.

The homepage subtitle now comes from a translatable string, so nothing reads it.

lmac-1 · 2026-10-05T14:33:59Z


 module.exports = {
  title: 'OpenFn/docs',
-  tagline:


removed on purpose as it's not referenced anywhere else. it would get stale with translations if ever picked up again.

It only runs the check now, so the --check flag goes too.

lmac-1 · 2026-10-05T14:35:56Z

 An Input is the data (`json`) that is used as the starting Input for a Workflow
-Step to utilise when it's run. Every Run will have an Input (initial state) and
-Output (final state).
+Step to utilise when it's run. Every Run has an Input (the initial `state`) and


This slight rewording is expected and the Spanish translation is based on this updated file.

Translate the interface text and these sections into Spanish: Get Started, tutorials, Design Workflows, Write Jobs, Platform, Build, CLI, deploy, get-help, contribute and unit testing. - Target neutral Latin American Spanish (es-419), and add house style rules to es.md from each review-translation pass. - Translate only the blocks whose English changed. Add check-translation.js, which shows the old translation and a word diff for each changed block. - Show a banner on non-Englishnglish.

The old anchor one-liner slugged the raw markdown, so the four "See ..." headings got anchors containing their GitHub URLs.

Drop the unused needs-review status, say what to do when an English page moves or is deleted, and run /translate interface for any <Translate> text in src/.

lmac-1 and others added 30 commits September 30, 2026 14:05

Prepare the site for translation

7478c02

Wrap the homepage copy in Translate so it can be extracted, give generated adaptor sidebar items unique keys so a second locale can build, and declare the i18n config with English as the only locale. Nothing changes for readers.

Keep homepage highlight links in the reader's locale

ed1912d

The highlight cards used a plain <a href> with a relative path, which dropped the locale prefix. Use Link with an absolute path so baseUrl, including /es/, is applied.

Ask before editing sidebars-adaptors.js

3e8470e

It generates the adaptor sidebar and now carries the keys that let a second locale build, so an edit there can break translated builds without touching English.

Merge pull request #878 from OpenFn/i18n-setup

c31e740

Prepare the site for translation

Turn on Spanish without linking to it

df94414

Build the es locale at /es/ so the translate skill can run against it, but keep the language dropdown out of the navbar until Spanish is ready for readers.

Explain how to run the site in Spanish locally

aa0d453

Close the Workflows callout with :::

d3e0675

The callout on the terminology page ended with `:::note` instead of `:::`.

Mark state as the state object on the terminology page

c953079

"initial state" and "final state" read as ordinary words, so translations turned them into ordinary words too. Formatting them as `state` makes it clear they name the object, which glossary.yml keeps in English.

Say where the translate skill records problems in the English

e064029

Keep custom code.json strings and format the translate skill

17a8e80

Remove only theme.* from code.json so new custom strings are not deleted. Show the do-not-retranslate example as Prettier leaves it, and run Prettier on the skill files and AGENTS.md.

Merge pull request #880 from OpenFn/translate-skill-split

e877ad6

Split the translate skill into pages and interface tasks

Keep the blog and articles titles in the translate skill

260d4e0

These files hold only the section titles and sidebar heading, not the posts, so they are translated like the rest of the interface.

Let project, credential, collection and operation be translated

485dbae

Add project, credential, collection and operation back to the glossary

d0fa81e

They now have a Spanish translation pinned under locales.

Merge branch 'main' into i18n

4b50306

# Conflicts: # .agents/skills/translate/SKILL.md

Translate only changed blocks, and add a side-by-side review script

51ba069

The translate skill now keeps the translation of every block whose English has not changed, and checks glossary terms block by block.

Show review blocks stacked, English above the translation

62e87fe

Drop the entregables translation rule

6f78f9d

The English says "Key Outputs", not "deliverables", so the rule never matched and "Resultados clave" was already right.

Restore the rules key in translation-rules.yml

4d2610f

The previous commit deleted one line too early.

Merge remote-tracking branch 'origin/main' into i18n

f441c65

# Conflicts: # .agents/skills/translate/SKILL.md

Check that the branch has the latest main before translating

3d453e0

Commit a translation before reviewing it, and check every block

4c3fcc5

Keep glossary terms in English unless locales gives a word

7d43153

Every glossary term is translate: false again. A term's locales entry (es: proyecto) overrides the English for that locale only, so a new locale keeps the English until someone adds a word for it.

Merge branch 'main' into i18n

2b4713e

lmac-1 added 2 commits October 2, 2026 11:18

Add the language dropdown to the navbar

ca715a4

Merge branch 'main' into i18n

96b7432

github-project-automation Bot added this to Documentation Oct 2, 2026

lmac-1 added 3 commits October 5, 2026 15:03

Check for rule changes by commit ancestry, not commit time

ef4182b

Remove the unused tagline from the site config

aa8b7fb

The homepage subtitle now comes from a translatable string, so nothing reads it.

lmac-1 commented Oct 5, 2026

View reviewed changes

Rename side-by-side.js to check-translation.js

f5ac477

It only runs the check now, so the --check flag goes too.

lmac-1 commented Oct 5, 2026

View reviewed changes

Note in AGENTS.md that the build covers every locale

bc04193

midigofrank approved these changes Oct 6, 2026

View reviewed changes

lmac-1 and others added 3 commits October 6, 2026 10:43

Fix the Spanish roadmap anchors that included link URLs

c637ea7

The old anchor one-liner slugged the raw markdown, so the four "See ..." headings got anchors containing their GitHub URLs.

Tidy the translate skills after the Spanish rollout

e261053

Drop the unused needs-review status, say what to do when an English page moves or is deleted, and run /translate interface for any <Translate> text in src/.

lmac-1 merged commit 6f29581 into main Oct 6, 2026
1 check passed

Navigation Menu

Add Spanish translation of the docs - #902

Add Spanish translation of the docs#902
lmac-1 merged 40 commits into
mainfrom
i18n

lmac-1 commented Oct 2, 2026 •

edited

Loading

Uh oh!

lmac-1 Oct 5, 2026

Uh oh!

lmac-1 Oct 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lmac-1 commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Short Description

Details

AI Usage

Uh oh!

lmac-1 Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

lmac-1 Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lmac-1 commented Oct 2, 2026 •

edited

Loading