readme-i18n

Visão geral da skill readme-i18n

O que a readme-i18n faz

readme-i18n é uma skill focada em transformar um único README.md no estilo GitHub em um conjunto multilíngue de READMEs fácil de manter. Não se trata de localização geral de apps. Sua função principal é traduzir o README de origem, criar arquivos paralelos como README.zh.md, preservar a estrutura do Markdown e a mecânica do repositório, além de adicionar ou padronizar um seletor de idiomas compartilhado entre todas as variantes.

Para quem a readme-i18n é indicada

Essa skill é ideal para maintainers, contribuidores de open source e agentes de IA que trabalham na documentação de repositórios quando o objetivo real não é apenas “traduzir texto”, mas “entregar arquivos README traduzidos que continuem funcionando no GitHub”. Se você quer manter badges, links, blocos de código, nomes de arquivo e alternância de idioma consistentes, readme-i18n é um ponto de partida melhor do que um prompt genérico de tradução.

O trabalho real que precisa ser resolvido

A maioria das tentativas de traduzir README falha na estrutura, não no vocabulário. O que os usuários precisam é de um fluxo de trabalho que:

• trate um arquivo como fonte da verdade
• mantenha a ordem das seções alinhada
• preserve comandos, caminhos, código e a mecânica dos links
• atualize todas as variantes de idioma com consistência
• evite seletores de idioma duplicados ou quebrados

Esse é o valor prático da readme-i18n skill.

Por que essa skill é diferente de um prompt comum

O principal diferencial está na lógica de decisão. A skill orienta o agente sobre o que deve ser preservado exatamente, quando vale pedir um esclarecimento pontual, como inferir convenções com base nos arquivos existentes e como atualizar um seletor no próprio lugar em vez de criar outro. As referências incluídas são especialmente úteis para adoção porque reduzem a adivinhação comum em torno de posicionamento de seletor e do tratamento seguro de Markdown durante a tradução.

Como usar a skill readme-i18n

Contexto de instalação da readme-i18n

Instale a skill a partir do repositório xixu-me/skills em qualquer ambiente compatível com Skills que você já utilize. Se a sua configuração aceitar instalação direta via GitHub, o padrão mais comum é:

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

Se o seu ambiente gerencia skills de outra forma, use a URL do repositório https://github.com/xixu-me/skills/tree/main/skills/readme-i18n como referência de origem e carregue a skill a partir de skills/readme-i18n.

Arquivos para ler antes do primeiro uso

Para essa skill, o caminho de leitura mais rápido e com maior sinal é:

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

Essa ordem importa. SKILL.md traz o fluxo de trabalho, a referência do seletor mostra o formato e o posicionamento esperados do bloco, e a checklist de preservação deixa claro o que precisa permanecer inalterado.

Quais entradas a readme-i18n precisa

A skill funciona melhor quando você fornece:

• caminho do README de origem, normalmente README.md
• idioma de origem
• idioma ou idiomas de destino
• glossário ou termos que não devem ser traduzidos
• convenção de nomes de arquivo já existente, se o repositório já localiza READMEs

Se você omitir os idiomas de destino, a skill foi pensada para primeiro inspecionar arquivos já traduzidos, seletores, nomes de arquivo, issues ou convenções do repositório. Se mesmo assim o idioma não ficar claro, ela deve perguntar uma vez em vez de inventar destinos.

Suposições padrão que vale conhecer

Os padrões documentados são práticos e vale conhecê-los antes de rodar readme-i18n:

• o README.md na raiz é a fonte da verdade, salvo indicação em contrário
• o idioma de origem é assumido como inglês quando não houver ambiguidade
• a ordem das seções deve permanecer alinhada à origem
• esquemas de nomenclatura multilíngue já existentes devem ser preservados em vez de substituídos por um novo

Esses padrões tornam a skill mais segura para repositórios existentes do que um pedido de tradução em branco.

Como fazer bons prompts para a readme-i18n

Um pedido fraco seria: “Translate my README into Chinese.”

Um prompt de readme-i18n usage mais forte é:

• 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

Esse nível extra de especificidade melhora diretamente a qualidade da saída porque se alinha às regras de preservação e seletor da skill.

Exemplo de fluxo de trabalho da readme-i18n para tradução

Um fluxo de readme-i18n for Translation prático é:

1. Identificar qual README é a fonte da verdade.
2. Verificar se já existem variantes traduzidas.
3. Detectar o padrão de nomes de arquivo do repositório e o estilo atual do seletor.
4. Traduzir apenas o conteúdo em linguagem natural.
5. Preservar exatamente código, comandos, URLs e caminhos de arquivo.
6. Adicionar ou padronizar um único bloco de seletor perto do topo em cada variante.
7. Verificar links, formatação e consistência entre todos os arquivos.

Esse é o modelo mental correto: não “traduzir texto”, mas “manter uma família de READMEs”.

Como o seletor de idiomas da readme-i18n deve funcionar

O arquivo de apoio mais forte dessa skill é a referência do seletor. Ela recomenda um único bloco de seletor próximo ao topo de cada variante de README, geralmente depois do título e do conjunto de badges, com marcadores estáveis:

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

Esses marcadores importam porque execuções futuras podem atualizar o seletor no próprio lugar. O idioma atual deve receber destaque e não ter link; os demais idiomas devem apontar para links. Mantenha a mesma ordem de idiomas em todas as variantes.

O que a readme-i18n deve preservar exatamente

A checklist de preservação é a parte mais crítica para adoção neste readme-i18n guide. Na prática, não traduza:

• código inline
• blocos de código fenced
• comandos, flags, env vars, caminhos
• badge URLs e query params
• caminhos de origem de imagens
• estrutura de tabelas
• mecânica de HTML bruto

Traduza o texto visível, mas preserve a mecânica que faz o README funcionar.

Convenções de repositório que a readme-i18n respeita

Se o repositório já usa um esquema de nomes diferente do padrão:

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

a skill deve preservar esse esquema. Isso é importante para repositórios que já têm localização parcial, referências em CI ou expectativa dos contribuidores vinculadas aos nomes dos arquivos.

Onde a readme-i18n economiza mais tempo

Essa skill é mais valiosa quando existe algum destes bloqueios de adoção:

• você precisa manter vários arquivos README localizados em sincronia
• o repositório já tem um alternador de idiomas bagunçado ou duplicado
• traduções anteriores quebraram o Markdown ou os links
• você quer atualizações repetíveis, e não edições manuais pontuais

Se você só precisa de uma tradução aproximada e privada para entender um README, essa skill provavelmente traz mais processo do que o necessário.

FAQ da skill readme-i18n

A readme-i18n é boa para iniciantes?

Sim, se o seu objetivo for especificamente localização de README. A skill reduz a tarefa a entradas claras e regras de preservação, o que é mais fácil do que inventar seu próprio fluxo de tradução. Ainda assim, iniciantes precisam revisar a saída, especialmente os destinos dos links, os títulos e a consistência do seletor.

Quando devo usar a readme-i18n em vez de um prompt comum de tradução?

Use readme-i18n quando o README traduzido for ser commitado no repositório. Um prompt comum pode traduzir demais, alterar exemplos de código, quebrar links de badges ou esquecer a navegação entre arquivos. Essa skill é melhor quando a correção da saída importa mais do que a velocidade.

A readme-i18n serve apenas para repositórios no GitHub?

Ela é otimizada para READMEs de repositório no estilo GitHub e para convenções de Markdown desse ecossistema. Ainda pode ajudar em outras plataformas baseadas em Git, mas suas suposições se alinham mais a repositórios open source baseados em README.md do que a sites completos de documentação ou sistemas de localização de produto.

A readme-i18n lida com conjuntos completos de documentação?

Não. Este é um fluxo focado em README. Se você precisa de i18n para site, app ou documentação inteira, a readme-i18n skill é restrita demais. O ponto forte dela é manter consistente um documento principal de entrada do repositório e seus arquivos irmãos localizados.

Quais idiomas posso usar?

A skill é agnóstica em relação ao idioma, desde que você especifique os destinos ou que o repositório já os deixe claros. Ela evita explicitamente inventar idiomas de destino quando o repositório não fornece evidência suficiente.

A readme-i18n pode atualizar uma estrutura multilíngue de README que já existe?

Sim, e esse é um dos melhores casos de uso. Ela foi projetada para inspecionar arquivos traduzidos e seletores atuais, preservar convenções de nomenclatura e padronizar um alternador existente em vez de adicionar um segundo.

Quando a readme-i18n não é uma boa escolha?

Evite usar quando:

• você só quer uma tradução informal para leitura
• sua documentação vive fora do README
• você precisa de gestão terminológica em um corpus grande de documentação
• seu repositório não quer links de seletor de idioma em arquivos README

Nesses casos, um prompt mais leve ou um fluxo mais amplo de localização de documentação pode fazer mais sentido.

Como melhorar a skill readme-i18n

Dê à readme-i18n restrições de origem mais fortes

Entradas melhores geram variantes de README melhores. Inclua:

• caminho exato do arquivo de origem
• locales de destino exatos
• termos que nunca devem ser traduzidos
• autônimos preferidos para os nomes dos idiomas
• se arquivos traduzidos existentes devem ser sobrescritos ou apenas atualizados

Isso reduz o modo de falha mais comum: tradução correta, comportamento errado no repositório.

Forneça um glossário de nomes e termos técnicos

Se o seu README contém nomes de produto, comandos de CLI, nomes de pacote ou terminologia específica do domínio, liste isso explicitamente. readme-i18n já tenta preservar elementos literais, mas um glossário curto melhora a consistência em títulos, descrições de recursos e exemplos.

Diga à skill no que ela não deve mexer

Uma das melhores formas de melhorar o readme-i18n usage é definir limites rígidos:

• manter todos os blocos de código byte a byte idênticos
• preservar links relativos
• não renomear arquivos, a menos que seja solicitado
• não mudar os destinos dos badges
• não reordenar seções

Essas instruções se alinham diretamente à checklist de preservação e evitam edições “úteis”, mas prejudiciais.

Revise o posicionamento do seletor antes de commitar

Um problema comum na saída é um alternador de idiomas estranho ou duplicado. Compare o seletor gerado com references/language-selector-reference.md e verifique:

• existe apenas um seletor por arquivo
• o posicionamento é consistente entre as variantes
• o idioma atual está em negrito, sem link
• os links apontam para os nomes reais dos arquivos irmãos

É uma etapa pequena de revisão, mas com alto retorno.

Verifique títulos localizados e âncoras

Títulos traduzidos podem mudar o comportamento das âncoras geradas em plataformas que derivam fragment IDs do texto do heading. A skill tenta preservar a hierarquia dos títulos, mas ainda assim vale testar links internos de heading após a tradução, especialmente em READMEs longos.

Faça iteração a partir das mudanças na origem, não de edições avulsas

Para manutenção de longo prazo, mantenha README.md como fonte da verdade e rode readme-i18n novamente a partir das atualizações da origem, em vez de editar manualmente cada arquivo localizado de forma independente. Isso mantém ordem de seções, conteúdo do seletor e terminologia alinhados ao longo do tempo.

Use verificação lado a lado após a primeira execução

Depois da primeira passada, compare os arquivos de origem e destino quanto a:

• mesma quantidade de seções
• mesma quantidade de blocos de código
• mesmas tabelas e estrutura de listas
• mesmas imagens e badges
• links do seletor funcionando

Isso detecta regressões estruturais mais rápido do que reler cada frase.

Melhore execuções futuras com convenções explícitas do repositório

Se o seu repositório tiver um padrão multilíngue fora do comum, diga isso diretamente no prompt da próxima vez que chamar readme-i18n. Exemplos:

• “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”

A skill se torna muito mais confiável quando as convenções do repositório são declaradas em vez de inferidas.