readme-i18n

Overview of readme-i18n skill

What readme-i18n does

readme-i18n is a focused skill for turning a single GitHub-style README.md into a maintainable multilingual README set. It is not general app localization. Its core job is to translate the source README, create sibling files like README.zh.md, preserve Markdown and repo mechanics, and add or normalize a shared language selector across all variants.

Who should use readme-i18n

This skill fits maintainers, open-source contributors, and AI agents working on repository docs where the real goal is not just “translate text,” but “ship translated README files that still work on GitHub.” If you care about badges, links, code fences, file naming, and language switchers staying consistent, readme-i18n is a better starting point than a generic translation prompt.

The real job to be done

Most README translation attempts fail on structure, not vocabulary. Users need a workflow that:

• treats one file as source-of-truth
• keeps section order aligned
• preserves commands, paths, code, and link mechanics
• updates every language variant consistently
• avoids duplicate or broken language selectors

That is the practical value of the readme-i18n skill.

Why this skill is different from a normal prompt

The main differentiator is decision logic. The skill tells the agent what to preserve exactly, when to ask once for clarification, how to infer conventions from existing files, and how to update a selector in place instead of creating another one. The included references are especially useful for adoption because they reduce the usual guesswork around selector placement and translation-safe Markdown handling.

How to Use readme-i18n skill

readme-i18n install context

Install the skill from the xixu-me/skills repository in whatever Skills-compatible environment you already use. If your setup supports direct GitHub installs, the common pattern is:

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

If your environment manages skills differently, use the repo URL https://github.com/xixu-me/skills/tree/main/skills/readme-i18n as the source reference and load the skill from skills/readme-i18n.

Files to read before first use

For this skill, the fastest high-signal reading path is:

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

That order matters. SKILL.md gives the workflow, the selector reference shows the expected block shape and placement, and the preservation checklist tells you what must stay unchanged.

What input readme-i18n needs

The skill works best when you provide:

• source README path, usually README.md
• source language
• target language or languages
• any glossary or do-not-translate terms
• existing filename convention if the repo already localizes READMEs

If you omit target languages, the skill is designed to inspect existing translated files, selectors, filenames, issues, or repo conventions first. If the language still is not clear, it should ask once rather than inventing targets.

Best default assumptions to know

The documented defaults are practical and worth knowing before you run readme-i18n:

• root README.md is the source-of-truth unless you say otherwise
• source language is assumed to be English if it is not ambiguous
• section order should stay aligned with the source
• existing multilingual naming schemes should be preserved instead of forcing a new one

These defaults make the skill safer for existing repos than a blank translation request.

How to prompt readme-i18n well

A weak request is: “Translate my README into Chinese.”

A stronger readme-i18n usage prompt is:

• translate README.md from English to Simplified Chinese
• create README.zh.md
• preserve commands, paths, badge URLs, code fences, and relative links
• add a top language selector to both files
• keep heading order identical
• do not translate product name AcmeCLI or env vars
• follow any existing filename convention if found

That extra specificity directly improves output quality because it matches the skill’s preservation and selector rules.

Example workflow for Translation

A practical readme-i18n for Translation workflow is:

1. Identify the source-of-truth README.
2. Check whether translated variants already exist.
3. Detect the repo’s filename pattern and current selector style.
4. Translate only human-language content.
5. Preserve code, commands, URLs, and file paths exactly.
6. Add or normalize one selector block near the top of every variant.
7. Verify links, formatting, and consistency across all files.

This is the right mental model: not “translate text,” but “maintain a README family.”

How the language selector should work

The strongest support file in this skill is the selector reference. It recommends one selector block near the top of every README variant, usually after the title and badge cluster, with stable markers:

<!-- README-I18N:START -->
<!-- README-I18N:END -->

Those markers matter because future runs can update the selector in place. The current language should be emphasized and not linked; other languages should be linked. Keep the language order the same across variants.

What must be preserved exactly

The preservation checklist is the adoption-critical part of this readme-i18n guide. In practice, do not translate:

• inline code
• fenced code blocks
• commands, flags, env vars, paths
• badge URLs and query params
• image source paths
• table structure
• raw HTML mechanics

Translate visible prose, but preserve the mechanics that make the README function.

Common repo conventions readme-i18n respects

If the repo already uses a naming scheme other than the default:

• README.md
• README.zh.md
• README.es.md

the skill should preserve that scheme. This is important for repos that already have partial localization, CI references, or contributor expectations tied to file names.

Where readme-i18n saves the most time

This skill is most valuable when one of these adoption blockers exists:

• you need multiple localized README files kept in sync
• the repo already has a messy or duplicated language switcher
• past translations broke Markdown or links
• you want updates to be repeatable instead of one-off manual edits

If you only need a rough private translation to understand a README, this skill is probably more process than you need.

readme-i18n skill FAQ

Is readme-i18n good for beginners?

Yes, if your goal is specifically README localization. The skill narrows the task into clear inputs and preservation rules, which is easier than inventing your own translation workflow. Beginners still need to review the output, especially link targets, headings, and selector consistency.

When should I use readme-i18n instead of a normal translation prompt?

Use readme-i18n when the translated README will be committed to a repo. A normal prompt may translate too much, alter code examples, break badge links, or forget cross-file navigation. This skill is better when output correctness matters more than speed.

Is readme-i18n only for GitHub repositories?

It is optimized for GitHub-style repository READMEs and Markdown conventions. It can still help on other Git-hosted platforms, but its assumptions are most aligned with README.md-based open-source repos rather than full docs sites or product localization systems.

Does readme-i18n handle full documentation sets?

No. This is a README-focused workflow. If you need website, app, or whole-docs i18n, readme-i18n skill is too narrow. Its strength is keeping one repository landing document and its localized siblings consistent.

What languages can I use?

The skill is language-agnostic as long as you specify the targets or the repo already makes them clear. It explicitly avoids inventing target languages when the repo does not provide enough evidence.

Can readme-i18n update an existing multilingual README setup?

Yes, and that is one of the best use cases. It is designed to inspect current translated files and selectors, preserve naming conventions, and normalize an existing switcher rather than adding a second one.

When is readme-i18n a bad fit?

Skip it when:

• you only want an informal reading translation
• your docs live outside the README
• you need terminology management across a large docs corpus
• your repo does not want language-selector links in README files

In those cases, a lighter prompt or a broader docs localization workflow may fit better.

How to Improve readme-i18n skill

Give readme-i18n stronger source constraints

Better inputs produce better README variants. Include:

• exact source file path
• exact target locales
• terms never to translate
• preferred autonyms for language names
• whether existing translated files should be overwritten or only updated

This reduces the most common failure mode: correct translation, wrong repo behavior.

Provide a glossary for names and technical terms

If your README contains product names, CLI commands, package names, or domain-specific terminology, list them explicitly. readme-i18n already tries to preserve literals, but a short glossary improves consistency in headings, feature descriptions, and examples.

Tell the skill what not to touch

One of the best ways to improve readme-i18n usage is to state hard boundaries:

• keep all code blocks byte-for-byte identical
• preserve relative links
• do not rename files unless asked
• do not change badge targets
• do not reorder sections

These instructions align tightly with the preservation checklist and prevent “helpful” but harmful edits.

Review selector placement before committing

A common output issue is an awkward or duplicated language switcher. Compare the generated selector against references/language-selector-reference.md and check:

• only one selector exists per file
• placement is consistent across variants
• current language is bold, not linked
• links point to the actual sibling filenames

This is a small review step with high payoff.

Check localized headings and anchors

Translated headings can change generated anchor behavior on platforms that derive fragment IDs from heading text. The skill aims to preserve heading hierarchy, but you should still test internal heading links after translation, especially in long READMEs.

Iterate from source changes, not ad hoc edits

For long-term maintenance, keep README.md as the source-of-truth and rerun readme-i18n from source updates instead of hand-editing every localized file independently. That keeps section order, selector content, and terminology aligned over time.

Use side-by-side verification after the first run

After the first pass, compare source and target files for:

• same section count
• same code block count
• same tables and list structure
• same images and badges
• working selector links

This catches structural regressions faster than rereading every sentence.

Improve future runs with explicit repo conventions

If your repo has a nonstandard multilingual pattern, state it directly in the prompt the next time you invoke readme-i18n. Examples:

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

The skill becomes much more reliable when repo conventions are named instead of inferred.