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.
Algumas distribuições Linux (como o Debian Bullseye, por exemplo) possuem
versões muito antigas do po4a
. Certifique-se de instalar uma versão
compatível. Se você estiver usando o Debian Bullseye, por exemplo, pode
baixar o arquivo Bookworm po4a.deb em
https://packages.debian.org
e instalá-lo manualmente.
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.
Pode haver links para esta documentação em outros lugares da web. Tente não alterar os URLs das páginas de documentação. Ou, pelo menos, insira links para o novo local no URL anterior.
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:
Esta funcionalidade está disponível com o plugin livechat versão 12.0.0.
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
.