mikaellolbatera159-stack/localizations

Localizar conteúdos em determinados idiomas

Uma habilidade que localiza conteúdos em determinados idiomas.

Como funciona

A habilidade recebe um conteúdo de entrada e uma lista de idiomas de destino. Em seguida, traduz o conteúdo para cada idioma especificado, fornecendo versões localizadas para cada um.

Estrutura de conteúdo

.
└── docs/                         ← conteúdo do workshop (fonte + saídas localizadas)
    ├── README.md                 ← página inicial (fonte; slug: index)
    ├── <category>/               ← categoria do workshop em inglês
    │   ├── README.md             ← página inicial da categoria (fonte; slug: <category>)
    │   └── <workshop>/
    │       ├── README.md         ← página inicial do workshop (fonte; slug: <category>/<workshop>)
    │       └── *.md
    ├── _images/              ← ativos compartilhados (não localizados)
    └── <locale>/             ← saída localizada, filha direta de docs/
        ├── README.md         ← página inicial do idioma (slug: <locale>)
        └── <category>/
            ├── README.md         ← página inicial da categoria localizada (slug: <locale>/<category>)
            └── <workshop>/
                ├── README.md     ← página inicial do workshop localizado (slug: <locale>/<category>/<workshop>)
                └── *.md

Conteúdos de entrada

Aqui estão os conteúdos no escopo para localização:

• Todos os arquivos Markdown em inglês sob docs/ e seus subdiretórios — a página inicial do site (docs/README.md), páginas iniciais de categorias e lições de workshops (docs/<category>/<workshop>/**/*.md).

Não trate _images/ (ativos compartilhados) ou qualquer diretório raiz de idioma configurado como entrada de origem.

Arquivos já existentes em docs/<locale>/ são saídas, não entradas — nunca trate diretórios raiz de idioma configurados como conteúdo de origem a ser localizado novamente.

Idiomas de destino

Os idiomas de destino são definidos no diretório rules como arquivos markdown nesta habilidade (rules/ko-kr.md, por exemplo). Para determinar quais idiomas processar, liste os arquivos em rules/: cada arquivo <locale>.md corresponde exatamente a um idioma de destino suportado. Cada idioma possui seu próprio conjunto de regras e diretrizes para tradução, garantindo que o conteúdo localizado seja apropriado para o público-alvo.

Os identificadores de idioma usam letras minúsculas com hífen (por exemplo, ko-kr). Esta é a capitalização canônica tanto para o nome do arquivo de regras quanto para o diretório de saída nesta habilidade; mantenha-os consistentes.

Conteúdos de saída

Todo o conteúdo do workshop localizado é armazenado diretamente sob o diretório raiz docs/ do repositório, com cada idioma tendo seu próprio subdiretório. Por exemplo, o conteúdo em coreano é armazenado em docs/ko-kr/.

Os diretórios de idioma devem ser filhos diretos de docs/ para que o Starlight (configurado em website/astro.config.mjs) os reconheça e renderize seu seletor de idioma. Não adicione um diretório intermediário localizations/.

Processo de localização

Existem três casos para localização. Para detectar qual caso se aplica, compare a árvore de origem com a árvore docs/<locale>/ existente e use o histórico do git dos arquivos de origem para detectar alterações:

• Original existe, nenhuma versão localizada para o idioma: Crie um novo documento localizado.
• Ambas as versões, original e localizada, existem: Compare a árvore de origem com docs/<locale>/, então execute git diff (ou git log) no arquivo de origem para encontrar o que mudou desde que a versão localizada foi produzida pela última vez. Atualize apenas as seções afetadas do documento localizado; não retraduza seções não alteradas desnecessariamente.
• Versão localizada existe, mas o original foi excluído: Exclua o documento localizado órfão (e remova subdiretórios de idioma agora vazios).

O processo é executado em duas etapas. Primeiro, o conteúdo é analisado para identificar frases-chave e contexto. Em seguida, o agente translator realiza a localização inicial, seguida por uma etapa de revisão e refinamento pelo agente evaluator para garantir qualidade e consistência.

Os "agentes" translator e evaluator são funções/personas, não ferramentas externas. Se não houver subagentes dedicados disponíveis, execute-os como personas sequenciais: primeiro adote a função de tradutor para produzir o rascunho, depois adote a função de avaliador para criticar e refinar esse rascunho de acordo com as regras do idioma. Repita o ciclo de refinamento até que os critérios do avaliador sejam aprovados.

Preservação de Markdown e formatação

Independentemente do idioma, o seguinte deve ser preservado exatamente e não traduzido:

• Chaves do YAML frontmatter (traduza apenas valores onde apropriado, por exemplo, um title). Exceção — a chave slug em páginas iniciais (README.md): o site roteia cada página inicial de pasta através de seu slug, portanto, uma página inicial localizada deve ter um slug prefixado com o idioma em vez do inglês. Reescreva-o: uma raiz de idioma (docs/<locale>/README.md) usa slug: <locale>, uma página inicial de categoria localizada usa slug: <locale>/<category> e uma página inicial de workshop localizado usa slug: <locale>/<category>/<workshop>. Nunca copie um slug de página inicial em inglês literalmente para um arquivo localizado, pois isso entraria em conflito com a rota em inglês.
• Código entre crases ou em blocos de código, incluindo nomes de variáveis, funções e comandos.
• URLs e destinos de links externos.
• Tags HTML, estrutura de Markdown, tabelas e marcadores de admonição.

Traduza prosa em linguagem humana, incluindo comentários dentro de blocos de código quando forem explicativos (de acordo com as regras do idioma). Mantenha a ordem dos cabeçalhos e a estrutura do documento estáveis.

As âncoras dos cabeçalhos seguem o texto localizado. Quando um cabeçalho é traduzido, sua âncora/slug gerada automaticamente muda com ele — isso é esperado. O requisito é que links de âncora no mesmo documento continuem resolvendo: sempre que você traduzir um cabeçalho, atualize todos os links na página que o referenciam (](#...)) para o novo slug do cabeçalho localizado. Não deixe um link apontando para o slug em inglês original depois que o cabeçalho for traduzido, e não preserve uma âncora em inglês que não corresponda mais ao seu cabeçalho. Âncoras que apontam para arquivos não localizados (ou URLs externas) mantêm seu destino original.

Caminhos de imagens e ativos apontam para os ativos originais, a menos que exista um ativo localizado. Como os arquivos localizados estão em docs/<locale>/, reescreva os caminhos relativos conforme necessário para que ainda resolvam para o ativo compartilhado (por exemplo, uma lição em docs/<locale>/real-world-development/app/2-foo.md usa ../../../_images/x.png para alcançar docs/_images/). Aponte para um ativo localizado apenas quando uma imagem traduzida correspondente existir na árvore do idioma. De qualquer forma, o link deve resolver para um arquivo real.

Agente tradutor

Use o agente translator para realizar a localização. Ele deve seguir as regras e diretrizes definidas para cada documento de idioma de destino no diretório rules.

Agente avaliador

Use o agente evaluator para avaliar a qualidade do conteúdo localizado. O avaliador verifica precisão, relevância cultural e qualidade geral, seguindo as regras e diretrizes definidas para o idioma de destino no diretório rules.

O avaliador pontua o documento localizado de acordo com a Rubrica de Pontuação do Avaliador do idioma (definida em rules/<locale>.md). A rubrica usa dois níveis: Nível A critérios de falha obrigatória que devem obter pontuação 5, e Nível B critérios graduados (1–5) que devem obter pontuação 4 ou 5. Um documento passa apenas quando cada critério aplicável do Nível A obtém 5 e cada critério aplicável do Nível B obtém ≥ 4. Se algo ficar abaixo, retorne o documento ao tradutor com anotações específicas e repita o ciclo de tradução → avaliação até que passe, escalando para um humano após o limite de iterações da rubrica.

O QUE FAZER e O QUE NÃO FAZER

• Faça a localização apenas para os idiomas de destino definidos no diretório rules (um <locale>.md por idioma suportado). Não localize para idiomas não suportados.
• Faça preservar a estrutura de Markdown, código, destinos de links/URLs externos e chaves de frontmatter exatamente (veja Preservação de Markdown e formatação).
• Faça permitir que as âncoras dos cabeçalhos sigam o texto do cabeçalho localizado e atualize os links de âncora no mesmo documento para corresponderem aos novos slugs, para que continuem resolvendo (veja Preservação de Markdown e formatação).
• Faça apontar caminhos de imagens e ativos para os ativos originais (reescrevendo o caminho relativo conforme necessário para que resolva a partir de docs/<locale>/), a menos que exista um ativo localizado correspondente (veja Preservação de Markdown e formatação).
• Faça espelhar a estrutura de diretórios de origem sob docs/<locale>/.
• Não trate diretórios raiz de idioma configurados como entrada de origem.
• Não reordene ou reestruture o conteúdo; mantenha os cabeçalhos e sua ordem estáveis.
• Não traduza código, comandos ou identificadores; traduza apenas prosa explicativa e comentários de código.