Documentació
Informació general
Anuncia’t sempre abans de començar a treballar (creant un tiquet o comentant un tiquet existent). Això és per evitar que diverses persones treballin en el mateix i entrin en conflicte.
El treball de documentació ha de fusionar-se a la branca main.
El codi font de la documentació es troba a la carpeta
support/documentation/content del repositori.
La documentació es genera mitjançant les eines Hugo, l’heu d’instal·lar a la vostra màquina per poder previsualitzar la documentació.
La versió mínima requerida d’Hugo és la 0.121.0. Hem provat amb la versió 0.132.2.
El tema utilitzat és hugo-theme-relearn. Es recomana llegir la seva documentació abans de començar.
Quan es publica una versió del connector o quan s’actualitza la
documentació, els responsables del connector fusionaran la branca main amb
la branca documentation. Això activarà les canonades github i gitlab i
n’actualitzarà les versions publicades.
Traduccions
L’idioma principal és l’anglès (codi en).
La carpeta support/documentation/content/en només conté fitxers de
documentació en anglès.
La documentació es tradueix mitjançant Weblate (vegeu documentació de traducció). Per fer-ho, utilitzem l’eina po4a, com veurem més endavant en aquesta pàgina.
Afegir un nou idioma
Al fitxer support/documentation/config.toml, inspira’t en la secció
[Languages.fr] per declarar el nou idioma.
Si les traduccions no estan completes, està bé, s’utilitzarà la versió en anglès per a les cadenes que falten.
Previsualitzar
Per previsualitzar les vostres modificacions només cal executar:
hugo serve -s support/documentation/A continuació obriu el vostre navegador a http://localhost:1313/peertube-plugin-livechat/. Aquesta pàgina s’actualitzarà automàticament amb cada modificació.
Actualitzar els fitxers de localització i generar traduccions de la documentació
De moment només teniu la versió en anglès. Per actualitzar les cadenes i
generar les traduccions, heu d’executar l’script doc-translate.sh.
Per fer-ho, assegureu-vos que teniu instal·lat po4a (versió >= 0.69) al vostre ordinador.
Algunes distribucions de Linux (com ara Debian Bullseye) tenen una versió
anterior de po4a. Assegureu-vos d’instal·lar-me una debcompatible. Si
utilitzeu Debian Bullseye podeu descarregar el fitxer Bookworm po4a.deb des
de
https://packages.debian.org,
i instal·lar-lo manualment.
Per gestionar les traduccions només cal fer el següent:
npm run doc:translateA continuació podeu previsualitzar el resultat utilitzant hugo serve -s support/documentation/ i utilitzant el selector d’idioma.
Escriure documentació
Editeu només fitxers en anglès a support/documentation/content/en.
Aleshores, abans de fer commit, executeu sempre npm run doc:translate,
de manera que els canvis en els fitxers en anglès es puguin propagar al
fitxer support/documentation/po/livechat.en.pot.
Podeu utilitzar el codi curt livechat_label per utilitzar cadenes de
l’aplicació. Vegeu aquí: Traducció de la
documentació.
És possible evitar que es tradueixi un fitxer utilitzant
livechatnotranslation: true a la secció Yaml Font Matter. Vegeu aquí:
Traducció de la
documentació.
Si us plau, utilitzeu l’opció livechatnotranslation per a la documentació
tècnica. No volem traduir documentació tècnica, per tal d’evitar problemes
relacionats amb una traducció deficient.
Per facilitar la feina dels traductors eviteu fer paràgrafs massa llargs.
De moment no és possible utilitzar les taules Markdown: les eines de traducció no saben com gestionar-les.
És possible que hi hagi enllaços a aquesta documentació en altres llocs del web. Intenteu no canviar els URL de les pàgines de documentació. O almenys posar enllaços a les pàgines noves als URL antics.
Quan hi hagi una funció nova disponible, podeu utilitzar
livechat_version_notice per mostrar un quadre d’informació amb la versió
en què aquesta funció està disponible. Aquest codi pren el número de versió
com a paràmetre. Aquí teniu un exemple:
Aquesta funció arriba amb la versió del complement Livechat 12.0.0.
Què he de fer si no puc utilitzar hugo i/o po4a?
Simplement editeu els fitxers de reducció en anglès i en fer «Pull Request» especifiqueu que no podeu compilar les traduccions.
Publicació
La publicació de la documentació és automàtica, tan bon punt les
modificacions es fusionen a la branca documentació.