Friday Release: Our README in Two Languages

Field trips EN2026-10-26

1. Set the README deadline and audience

Start with a concrete release target: for example, publish the English and Spanish README before Friday’s internal demo. Write down who will read it, what they need to do first, and which details must remain identical in both languages.

Keep the source README in English unless your team already works from another language. English usually gives developer tools the broadest context, while a second language can make installation and troubleshooting easier for local contributors. Decide whether the translated version will live in a separate file such as README.es.md or in a language switcher near the top of the document.

2. Clean the English source before asking AI for help

AI can translate unclear documentation faithfully, so edit the source before you send it anywhere. Remove duplicate installation steps, define unexplained acronyms, and make every command complete. A reader at a desk should be able to follow the sequence without guessing.

Confirm the project name, supported operating systems, runtime versions, and package manager.
Use one term consistently for each concept, such as token, endpoint, workspace, or relay.
Put commands on their own lines and keep placeholders visibly distinct from real values.
Mark claims that need verification, including version numbers, pricing, limits, and platform support.

3. Ask AI to build a translation brief first

Do not begin with “translate this README.” Give the model a compact brief that defines the job. State the target language, intended audience, regional spelling, tone, and terms that must remain unchanged. Tell it to preserve headings, list order, links, command syntax, environment variable names, file paths, and code blocks.

A useful instruction is: “Translate the following README into Spanish for software developers. Preserve all Markdown structure and technical tokens exactly. Do not translate product names, commands, URLs, environment variables, package names, or error messages. If a sentence is ambiguous, list it after the translation instead of guessing.”

4. Generate the second README in reviewable sections

Send the document in sections rather than pasting an entire large repository guide at once. Work through installation, configuration, usage, troubleshooting, and contribution notes separately. This keeps the output within a manageable context and makes comparison easier.

After each section, ask AI to return only the translated text and a short list of uncertainties. Save the result beside the source file. Do not let the model silently invent setup steps or replace a real command with a natural-language description.

5. Run a technical comparison at your desk

Open both files side by side and check the parts language models commonly damage. Compare every command, URL, option name, filename, heading anchor, link target, and warning. Then follow the installation instructions in a clean shell using the translated README alone.

Check that code fences, indentation, bullets, and numbering still render correctly.
Search both files for the same URLs, environment variables, and command names.
Verify that warnings retain their urgency and that “optional” has not become “recommended.”
Ask a native or highly fluent reviewer to inspect tone, terminology, and culturally awkward phrasing.

6. Use a second AI pass for consistency

Once the human review is complete, ask AI to compare the two versions as a documentation auditor. Give it both files and request a table of mismatched facts, missing sections, altered commands, and inconsistent terminology. This is a review task, not permission to rewrite the documents.

For model access during this workflow, RelayVano provides a pay-as-you-go relay for AI models and works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs. Its API base is https://api.relayvano.com. A lightweight model such as Claude Haiku 4.5 can handle terminology checks, while a larger model such as GPT-6 Astra may help with structural review. Sign up for RelayVano when you need a practical way to run these documentation passes across your existing tools.

7. Publish both files with a maintenance rule

Add a visible language link at the top of each README and define one owner for future updates. Treat the English file as the source of truth only if your team agrees to translate changes before release. Otherwise, label the translation with its last-reviewed date so readers can judge its freshness.

Finally, add the bilingual README to the same pull request as the feature or release it documents. A short review checklist in the pull request should confirm that both files contain the same installation path, configuration requirements, supported versions, and troubleshooting advice. That small habit keeps the second language useful after launch, instead of leaving it as a one-time translation artifact.