Documentação

informações gerais

Sempre informe a comunidade antes de trabalhar (criando um novo problema ou comentando um existente). Isso evita que duas pessoas trabalhem na mesma coisa e previne conflitos.

O trabalho de documentação deve ser mesclado no branch main.

O código-fonte da documentação está na pasta support/documentation/content.

A documentação é gerada usando Hugo. Você precisa instalá-lo no seu computador se quiser visualizar seu trabalho.

A versão mínima necessária para o Hugo é 0.121.0. Ele foi testado com a versão 0.132.2.

O tema usado é hugo-theme-relearn. Você deve ler a documentação antes de começar a editá-la.

Quando uma nova versão do plugin é lançada ou quando a documentação é atualizada, os mantenedores do plugin mesclam a ramificação “main” com a ramificação “documentation”. Isso acionará os pipelines do GitHub e do GitLab e atualizará a documentação publicada.

Traduções

O idioma principal é o inglês (código en).

A pasta support/documentation/content/en contém apenas arquivos de documentação em inglês.

A documentação é traduzida usando o Weblate (veja a documentação de tradução). Para isso, usamos a ferramenta po4a, como veremos mais adiante nesta página.

Adicionar um novo idioma

No arquivo support/documentation/config.toml, copie e modifique a seção [Languages.fr].

Se as traduções não estiverem completas, não importa, o inglês será usado para as strings faltantes.

Pré-visualização

Para visualizar suas modificações, basta executar:

hugo serve -s support/documentation/

Em seguida, abra seu navegador no endereço http://localhost:1313/peertube-plugin-livechat/. Esta página será atualizada automaticamente a cada modificação.

Atualizar arquivos de localização e gerar traduções de documentação

Por enquanto, você só tem a versão em inglês. Para atualizar as strings de documentação e gerar traduções, você precisa executar o script doc-translate.sh.

To do so, make sure you have po4a (version >= 0.69) installed on your computer.

Para lidar com traduções, basta fazer:

npm run doc:translate

Você pode então visualizar o resultado usando hugo serve -s support/documentation/ e usar o seletor de idioma.

Escrever documentação

Basta editar os arquivos em inglês em support/documentation/content/en.

Então, antes de confirmar, sempre execute npm run doc:translate, para que as alterações nos arquivos em inglês possam ser propagadas para o arquivo support/documentation/po/livechat.en.pot.

Você pode usar o código curto livechat_label para usar strings de aplicativo. Veja aqui: Tradução da documentação.

É possível impedir que um arquivo seja traduzido usando livechatnotranslation: true na seção Yaml Font Matter. Veja aqui: Tradução da documentação.

Use a opção livechatnotranslation para documentação técnica. Não queremos que a documentação técnica seja traduzida para evitar problemas devido a uma tradução incorreta.

Para facilitar o trabalho dos tradutores, evite fazer parágrafos muito longos.

Por enquanto, não é possível usar tabelas Markdown: as ferramentas de tradução irão quebrá-las.

Quando um novo recurso é lançado, você pode usar o código curto livechat_version_notice para exibir uma infobox com a versão em que o recurso está disponível. Este código curto recebe o número da versão como parâmetro. Veja um exemplo:

E se eu não puder usar hugo e/ou po4a?

Basta editar os arquivos markdown em inglês e especificar que você não pode criar traduções ao fazer seu Pull Request.

Publicação

A publicação da documentação é automática, assim que as alterações são mescladas na ramificação documentation.