Mantenha a documentação bilíngue alinhada
Guias de usuário públicos são emparelhados por caminho relativo:
docs/en/<caminho-relativo>
docs/ja/<caminho-relativo>
O inglês é publicado em /; o japonês é publicado em /ja/. O japonês permanece
a fonte prática de autoria para novas explicações de produto, mas uma edição em
qualquer idioma não deve deixar silenciosamente sua contraparte com comportamento,
comandos, limites de propriedade, avisos ou navegação diferentes.
Escopo
Aplique este fluxo de trabalho a index.md e guide/**/*.md abaixo de ambas as raízes de idioma.
docs/en/reference/ é intencionalmente apenas em inglês. Documentos internos de arquitetura,
decisão, repositório, contribuidor e testes futuros fora das duas raízes de idioma
não são pares de tradução.
Fluxo de trabalho
- Inspecione a alteração solicitada e o diff atual do Git. Identifique cada página pública afetada e sua contraparte de mesmo caminho relativo.
- Leia ambas as páginas completas. Quando o conteúdo japonês for criado, editado ou revisado quanto à legibilidade, leia também a referência de estilo japonesa. Quando a edição alterar o comportamento do produto, comandos, caminhos ou propriedade, verifique a fonte atual ou a Decisão aceita em vez de traduzir uma suposição.
- Preserve o significado, a arquitetura da informação, exemplos, avisos e destinos de links, mas escreva documentação natural para cada público em vez de traduzir frase por frase. Edite ambas as contrapartes quando o significado ou a estrutura da informação mudar. Para uma melhoria de redação apenas em japonês, inspecione a contraparte em inglês, mas não invente uma edição em inglês quando seu significado e estrutura já estiverem de acordo.
- Se uma contraparte não existir, crie-a. Se uma página for intencionalmente específica de um idioma, confirme que está fora do escopo emparelhado ou obtenha uma decisão explícita para adiá-la; relate o adiamento e seu local de rastreamento. Não declare a alteração bilíngue completa enquanto a divergência estiver meramente não mencionada.
- Para uma movimentação ou remoção, aplique a mesma alteração de caminho relativo a ambas as árvores e
atualize
mkdocs.yml, links de entrada, orientação para contribuidores e qualquer URL pública incorporada em código ou testes.
Verificação
Execute a partir da raiz do repositório:
python -m mkdocs build --strict
git diff --check
Confirme que as páginas geradas em inglês e japonês existem em caminhos correspondentes
e que seus seletores de idioma apontam uma para a outra. Quando uma URL pública
for um contrato de CLI, também atualize sua fonte, testes focados e Decisão aceita,
então execute o teste focado e python scripts/check_decisions.py.
Relate os pares de páginas inspecionados e alterados, qualquer contraparte intencionalmente deixada inalterada após comparação semântica, qualquer outra exceção e os resultados da verificação.