CONTRIBUTING.md

Contribuir para o Co-op Translator

Este projeto aceita contribuições e sugestões. A maioria das contribuições requer que concorde com um Acordo de Licença de Contribuidor (CLA) declarando que tem o direito e efetivamente concede-nos os direitos para usar a sua contribuição. Para mais detalhes, visite https://cla.opensource.microsoft.com.

Quando submeter um pull request, um bot de CLA determinará automaticamente se precisa fornecer um CLA e decorará o PR adequadamente (por exemplo, verificação de estado, comentário). Basta seguir as instruções fornecidas pelo bot. Só precisará fazer isto uma vez para todos os repositórios que usam o nosso CLA.

Configuração do ambiente de desenvolvimento

Para configurar o ambiente de desenvolvimento deste projeto, recomendamos usar o Poetry para gerir dependências. Usamos o pyproject.toml para gerir as dependências do projeto, pelo que deve usar o Poetry para instalar as dependências.

Criar um ambiente virtual

Usando pip

python -m venv .venv

Usando Poetry

poetry init

Ativar o ambiente virtual

Para pip e Poetry

• Windows:

  .venv\Scripts\activate.bat

• Mac/Linux:

  source .venv/bin/activate

Usando Poetry

poetry shell

Instalar o pacote e as dependências necessárias

Usando Poetry (a partir do pyproject.toml)

poetry install

Testes manuais

Antes de submeter um PR, é importante testar a funcionalidade de tradução com documentação real:

1. Crie um diretório de teste na raiz do projeto:

   mkdir test_docs

2. Copie alguma documentação em markdown e imagens que queira traduzir para o diretório de teste. Por exemplo:

   cp /path/to/your/docs/*.md test_docs/
   cp /path/to/your/images/*.png test_docs/

3. Instale o pacote localmente:

   pip install -e .

4. Execute o Co-op Translator nos seus documentos de teste:

   python -m co_op_translator --language-codes ko --root-dir test_docs

5. Verifique os ficheiros traduzidos em test_docs/translations e test_docs/translated_images para confirmar:

   • A qualidade da tradução
   • Os comentários de metadados estão corretos
   • A estrutura original do markdown está preservada
   • Os links e imagens funcionam corretamente

Este teste manual ajuda a garantir que as suas alterações funcionam bem em cenários reais.

Variáveis de ambiente

1. Crie um ficheiro .env na raiz do projeto copiando o ficheiro .env.template fornecido.
2. Preencha as variáveis de ambiente conforme indicado.

Tip

Opções adicionais para o ambiente de desenvolvimento

Para além de executar o projeto localmente, pode também usar GitHub Codespaces ou VS Code Dev Containers como alternativa para configurar o ambiente de desenvolvimento.

GitHub Codespaces

Pode executar estes exemplos virtualmente usando GitHub Codespaces, sem necessidade de configurações adicionais.

O botão abrirá uma instância do VS Code baseada na web no seu navegador:

1. Abra o template (isto pode demorar alguns minutos):

   

Executar localmente usando VS Code Dev Containers

⚠️ Esta opção só funciona se o seu Docker Desktop tiver pelo menos 16 GB de RAM alocados. Se tiver menos de 16 GB, pode tentar a opção GitHub Codespaces ou configurar localmente.

Uma opção relacionada é usar VS Code Dev Containers, que abrirá o projeto no seu VS Code local usando a extensão Dev Containers:

1. Inicie o Docker Desktop (instale-o se ainda não estiver instalado)

2. Abra o projeto:

   

Estilo de Código

Usamos o Black como formatador de código Python para manter um estilo consistente em todo o projeto. O Black é um formatador de código inflexível que reformata automaticamente o código Python para conformar ao estilo Black.

Configuração

A configuração do Black está especificada no nosso pyproject.toml:

[tool.black]
line-length = 88
target-version = ['py310']
include = '\.pyi?$'

Instalar o Black

Pode instalar o Black usando Poetry (recomendado) ou pip:

Usando Poetry

O Black é instalado automaticamente quando configura o ambiente de desenvolvimento:

poetry install

Usando pip

Se usar pip, pode instalar o Black diretamente:

pip install black

Usar o Black

Com Poetry

1. Formate todos os ficheiros Python do projeto:

   poetry run black .

2. Formate um ficheiro ou diretório específico:

   poetry run black path/to/file_or_directory

Com pip

1. Formate todos os ficheiros Python do projeto:

   black .

2. Formate um ficheiro ou diretório específico:

   black path/to/file_or_directory

Tip

Recomendamos configurar o seu editor para formatar automaticamente o código com Black ao guardar. A maioria dos editores modernos suporta isto através de extensões ou plugins.

Executar o Co-op Translator

Para executar o Co-op Translator usando Poetry no seu ambiente, siga estes passos:

1. Navegue até ao diretório onde pretende realizar os testes de tradução ou crie uma pasta temporária para esse efeito.

2. Execute o seguinte comando. Substitua -l ko pelo código da língua para a qual deseja traduzir. A flag -d indica modo de depuração.

   poetry run co-op-translator translate -l ko -d

Note

Certifique-se de que o ambiente Poetry está ativado (poetry shell) antes de executar o comando.

Contribuir com uma nova língua

Aceitamos contribuições que adicionem suporte a novas línguas. Antes de abrir um PR, por favor complete os passos abaixo para garantir uma revisão tranquila.

1. Adicione a língua ao mapeamento de fontes

   • Edite src/co_op_translator/fonts/font_language_mappings.yml
   • Adicione uma entrada com:
     • code: código da língua tipo ISO (ex.: vi)
     • name: nome amigável para exibição
     • font: uma fonte incluída em src/co_op_translator/fonts/ que suporte o alfabeto
     • rtl: true se for da direita para a esquerda, caso contrário false

2. Inclua os ficheiros de fonte necessários (se aplicável)

   • Se for necessária uma nova fonte, verifique a compatibilidade da licença para distribuição open source
   • Adicione o ficheiro da fonte em src/co_op_translator/fonts/

3. Verificação local

   • Execute traduções para uma pequena amostra (Markdown, imagens e notebooks conforme apropriado)
   • Verifique se a saída é renderizada corretamente, incluindo fontes e qualquer layout RTL se aplicável

4. Atualize a documentação

   • Assegure que a língua aparece em getting_started/supported-languages.md
   • Não é necessário alterar getting_started/README_languages_template.md; este é gerado a partir da lista suportada

5. Abra um PR

   • Descreva a língua adicionada e quaisquer considerações sobre fontes/licenciamento
   • Anexe capturas de ecrã da saída renderizada, se possível

Exemplo de entrada YAML:

new_lang(code):
  name: "New Language"
  font: "NotoSans-Medium.ttf"
  rtl: false

Testar a nova língua

Pode testar a nova língua executando o seguinte comando:

# Criar e ativar um ambiente virtual
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
# Instalar o pacote de desenvolvimento
pip install -e .
# Executar a tradução
translate -l "new_lang"

Mantenedores

Mensagem de commit e estratégia de merge

Para garantir consistência e clareza no histórico de commits do nosso projeto, seguimos um formato específico para a mensagem de commit na mensagem final quando usamos a estratégia Squash and Merge.

Quando um pull request (PR) é mergeado, os commits individuais são combinados num único commit. A mensagem final deve seguir o formato abaixo para manter um histórico limpo e consistente.

Formato da mensagem de commit (para squash and merge)

Usamos o seguinte formato para mensagens de commit:

<type>: <description> (#<número do PR>)

• type: Especifica a categoria do commit. Usamos os seguintes tipos:

  • Docs: Para atualizações de documentação.
  • Build: Para alterações relacionadas com o sistema de build ou dependências, incluindo atualizações a ficheiros de configuração, workflows CI, ou Dockerfile.
  • Core: Para modificações na funcionalidade ou características principais do projeto, especialmente aquelas envolvendo ficheiros na pasta src/co_op_translator/core.

• description: Um resumo conciso da alteração.

• PR number: O número do pull request associado ao commit.

Exemplos:

• Docs: Atualizar instruções de instalação para maior clareza (#50)
• Core: Melhorar o tratamento da tradução de imagens (#60)

Note

Atualmente, os prefixos Docs, Core e Build são adicionados automaticamente aos títulos dos PRs com base nas etiquetas aplicadas ao código fonte modificado. Desde que a etiqueta correta seja aplicada, normalmente não precisa de atualizar manualmente o título do PR. Só precisa de verificar se está tudo correto e se o prefixo foi gerado adequadamente.

Estratégia de merge

Usamos Squash and Merge como estratégia padrão para pull requests. Esta estratégia assegura que as mensagens de commit seguem o nosso formato, mesmo que os commits individuais não o façam.

Razões:

• Um histórico limpo e linear do projeto.
• Consistência nas mensagens de commit.
• Redução de ruído causado por commits menores (ex.: "corrigir erro de digitação").

Ao fazer merge, assegure que a mensagem final do commit segue o formato descrito acima.

Exemplo de Squash and Merge Se um PR contiver os seguintes commits:

• corrigir erro de digitação
• atualizar README
• ajustar formatação

Devem ser combinados em: Docs: Melhorar clareza e formatação da documentação (#65)

Processo de lançamento

Esta secção descreve a forma mais simples para os mantenedores publicarem uma nova versão do Co-op Translator.

1. Atualizar a versão no pyproject.toml

1. Decida o próximo número de versão (seguimos versionamento semântico: MAJOR.MINOR.PATCH).
2. Edite o pyproject.toml e atualize o campo version em [tool.poetry].
3. Abra um pull request dedicado que apenas altere a versão (e quaisquer ficheiros de bloqueio/metadados atualizados automaticamente, se existirem).
4. Após revisão, use Squash and Merge e assegure que a mensagem final do commit segue o formato descrito acima.

2. Criar um Release no GitHub

1. Vá à página do repositório no GitHub e abra Releases → Draft a new release.
2. Crie uma nova tag (por exemplo, v0.13.0) a partir da branch main.
3. Defina o título do release com a mesma versão (por exemplo, v0.13.0).
4. Clique em Generate release notes para preencher automaticamente o changelog.
5. Opcionalmente, edite o texto (por exemplo, para destacar novas línguas suportadas ou alterações importantes).
6. Publique o release.

---

Aviso Legal: Este documento foi traduzido utilizando o serviço de tradução automática Co-op Translator. Embora nos esforcemos para garantir a precisão, por favor tenha em conta que traduções automáticas podem conter erros ou imprecisões. O documento original na sua língua nativa deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.