Ansel usa Gettext  per tradurre tutte le parti del progetto:

  • L’applicazione software (scritta in C),
  • Il sito web (template Hugo e contenuti Markdown),
  • La documentazione/manuale utente, inserita nel sito web come modulo (anch’essa template Hugo e contenuti Markdown).

Questo garantisce che lo stesso flusso di lavoro possa essere usato per tradurre tutti i file, ma anche che alcune stringhe tradotte possano essere condivise (per esempio, i controlli della GUI tradotti delle applicazioni possono essere inseriti direttamente nella documentazione).

Organizzazione dei file di traduzione

Il codice sorgente del sito web, della documentazione e del software contiene tutto una sottocartella po/ immediata, contenente:

  • un file .pot che contiene tutte le stringhe traducibili disponibili nella loro lingua originale (in inglese),
  • molti file .po che associano le stringhe traducibili nella loro lingua originale alla loro traduzione (una lingua per file).

I file di traduzione sono tutti nominati seguendo la convenzione language-code.po. Per esempio:

  • per il tedesco,
    • la traduzione del software è de.po,
    • la traduzione del sito web è content.de.po,
    • la traduzione della documentazione è content.de.po,
  • per il portoghese brasiliano,
    • la traduzione del software è pt_BR.po,
    • la traduzione del sito web è content.pt_br.po,
    • la traduzione della documentazione è content.pt_br.po.

Tradurre quando non puoi usare CLI/Git

Dovrai individuare il file .po pertinente per la tua lingua relativo alla parte del progetto che vuoi tradurre:

  1. Scarica questo file e aprilo con Poedit ,
  2. Apporta le correzioni e le modifiche di cui hai bisogno,
  3. Aggiungi il tuo nome in un commento per le stringhe che traduci se vuoi essere accreditato nella pagina :
    • Le stringhe tradotte automaticamente avranno lì TRANSLATOR ChatGPT, una volta verificate quelle stringhe, rimuovi questa riga,
    • Poi aggiungi un commento contenente TRANSLATOR Your Name su una nuova riga. Mantieni gli altri collaboratori (non-ChatGPT) presenti, se ce ne sono.
  4. Salva il file e:
    • Alternativa 1 (più facile per il collaboratore, più passaggi per il maintainer): caricalo sul mio cloud privato ,
    • Alternativa 2 (più passaggi per il collaboratore, più facile per il maintainer): effettua il commit con Git e apri una pull request sul repository Github appropriato.

Tradurre per utenti esperti

Questo aggiornerà il file .pot usando il codice sorgente del progetto. Dovrai avere Git installato, e Hugo 0.146  installato sul tuo computer.

  1. Clona il codice sorgente del progetto pertinente:
    • il software :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • il sito web :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • la documentazione :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Successivamente, aggiornerai il repository usando :
    1$ git pull
  2. Aggiorna il file .pot e tutti i file .po dal codice sorgente (questo passaggio funziona allo stesso modo per tutti e 3 i progetti):
    1$ sh tools/update-translations.sh
  3. Traduci il file .po pertinente usando Poedit o direttamente in un editor di testo (vedi Tradurre quando non puoi usare CLI/Git),
  4. Testa e revisiona la tua traduzione :
    • Per il software, dovrai compilare Ansel sul tuo sistema operativo. Consulta la documentazione.
    • Per il sito web e la documentazione, puoi eseguire :
      1sh build-modules.sh
2hugo
    Fai attenzione a eventuali errori critici da po4a, specialmente per caratteri \n non corrispondenti, e agli errori da Hugo, specialmente riguardo alla sintassi degli shortcode.
  5. Per il sito web e la documentazione, ripulisci i file Markdown tradotti (generati automaticamente da po4a usando il file .po) prima di effettuare il commit, usando :
    1sh tools/build-translations.sh --remove
  6. Effettua il commit di tutti i file .pot e .po e apri una pull request sul repository Github pertinente. Non effettuare mai il commit dei file .md (Markdown) tradotti.

Tradurre le immagini

Quanto segue si applica solo al sito web e alla documentazione.

Anche le immagini possono essere tradotte, per esempio le schermate dell’applicazione. Le immagini sono memorizzate nella cartella assets/ se sono riutilizzate su più pagine (asset globali), altrimenti sono memorizzate nella stessa cartella del file Markdown che le usa (asset locali). Che siano globali o locali, il processo di traduzione è lo stesso, cambia solo la cartella di base.

Se, per esempio, vuoi tradurre assets/screenshot.jpg per la lingua LANG (che è il codice ISO della lingua, come de, nl, pt_br, zn_cn, ecc.):

  1. aggiungi ed effettua il commit di un nuovo file immagine assets/screenshot.LANG.jpg nel repository Git della documentazione o del sito web,
  2. nel content.LANG.po, individua la voce contenente il tag Markdown per l’immagine originale, che sarà qualcosa come ![alt text](screenshot.jpg),
  3. traduci il tag Markdown sostituendo l’URL dell’immagine, come ![translated alt text](screenshot.LANG.jpg,
  4. salva ed effettua il commit del file content.LANG.po,
  5. crea una pull request sul repository del sito web o della documentazione di Ansel.

Strumenti automatici e script di supporto

Inizializzare la traduzione della documentazione con quella del software

Poiché la documentazione e il software condividono le stesse stringhe per i controlli della GUI, puoi inizializzare pigramente le stringhe della documentazione da quelle del software se corrispondono esattamente (comprese le maiuscole/minuscole). Questo richiede un interprete Python e il pacchetto regex (installalo con pip install -U regex). Dal codice sorgente della documentazione, puoi chiamare :

1$ python tools/merge-translations.py path/to/software path/to/doc

Tradurre automaticamente documentazione e sito web con ChatGPT

ChatGPT-4o fa un lavoro piuttosto buono nel tradurre testo formattato in Markdown dall’inglese, anche se non in ogni lingua. Ti servirà una chiave API privata da memorizzare nella cartella della documentazione o del sito web in un file .chatgpt.api_key. Inoltre, le chiamate all’API di ChatGPT non sono gratuite, e il pagamento minimo di 5 US$ ti permetterà all’incirca di tradurre completamente il sito web in 4 lingue.

Lo script tutto-in-uno può essere chiamato usando :

1$ sh auto-translate.sh LANG

dove LANG è il codice della lingua di destinazione (de, fr, pt_br, ecc.). Questo elaborerà la traduzione in lotti da 90 a 120 stringhe per rispettare le limitazioni e le soglie dell’API di ChatGPT. Questo :

  • analizza il file originale po/content.LANG.po ed esporta il lotto da tradurre in un file temporaneo po/content.LANG.txt,
  • invia il file po/content.LANG.txt a ChatGPT e ottiene la risposta in po/content.LANG.generated.txt
  • corregge le incoerenze di formattazione più comuni che ChatGPT può introdurre e reinserisce le traduzioni in po/content.LANG.po,
  • compila i file Markdown tradotti (seguendo la convenzione di denominazione page.LANG.md),
  • compila il sito web con Hugo.

Se tutti questi passaggi si completano senza errori, allora puoi eseguire nuovamente lo script per elaborare il lotto successivo fino al completamento. Se vengono mostrati errori, dovrai correggerli. Eseguiamo solo un lotto a ogni chiamata per dare all’utente l’opportunità di trovare gli errori quando non ci sono troppe modifiche da ispezionare.

Errori comuni:

  • non verrà tradotto nulla : controlla la risposta di ChatGPT in po/content.LANG.generated.txt, a volte non è in grado di comprendere la sua missione. Puoi riprovare, a volte funziona alla 3ª chiamata. Ma spesso non c’è nulla da fare e alcune lingue/stringhe non possono essere tradotte affatto.
  • durante la compilazione del sito web con Hugo, alcuni shortcode non vengono trovati. Questo accade perché gli shortcode sono dichiarati così : {{< shortcode_name >}}. A volte, ChatGPT proverà a tradurre shortcode_name e lo shortcode non funzionerà più. La soluzione è ripristinare il nome inglese dello shortcode e dei suoi attributi,
  • lo stesso vale per i grafici Mermaid , ChatGPT può provare a tradurre comandi e proprietà che non dovrebbero essere tradotti,
  • le stringhe originali terminano con il carattere di nuova riga \n e le stringhe tradotte no (o viceversa). Lo script cerca di correggere questo, ma alcuni casi limite non vengono gestiti. Le stringhe originali msgid e la loro traduzione msgstr nel file .po dovrebbero avere lo stesso numero di caratteri \n nello stesso punto,
  • virgolette doppie con escape improprio : le stringhe Gettext msgid e msgstr dovrebbero essere delimitate da virgolette doppie senza escape " a ciascuna estremità della stringa. Qualsiasi altra virgoletta doppia, all’interno della stringa Gettext, dovrebbe avere l’escape usando \".

Il modo migliore per correggere gli errori è aprire il file .po pertinente in un editor di testo. Se non riesci a trovare l’errore e a risolverlo, puoi provare ad aprire il file in Poedit, ma al momento del salvataggio, di solito cancellerà completamente le stringhe difettose senza correggerle, quindi la traduzione dovrà essere ricominciata da zero.

Compilare i file Markdown tradotti

Per il sito web e la documentazione, Hugo  gestisce le traduzioni di una data pagina new_page.md usando la convenzione di denominazione new_page.LANG.md, dove LANG è il codice della lingua. Hugo supporta nativamente la scrittura manuale di questi file tradotti nella stessa cartella del loro originale, tuttavia, qui li generiamo usando il file di traduzione .po e il programma po4a. Gli script build-modules.sh e tools/auto-translate.sh gestiscono questo internamente, ma potresti voler generare quei file manualmente :

  1. Aggiorna i file .pot e .po con il codice sorgente :
    1$ sh tools/update-translations.sh
  2. Crea i file .md tradotti :
    1$ sh tools/build-translations.sh --add
  3. Ripulisci i file .md tradotti :
    1$ sh tools/build-translations.sh --remove

È importante non effettuare mai il commit dei file .md tradotti con Git, poiché vengono rigenerati solo da quello script durante la compilazione del sito web. Questo serve solo per l’igiene del repository, non c’è alcuno svantaggio tecnico. Ripulire i file .md tradotti prima di effettuare il commit garantisce l’assenza di errori.

Persi nella traduzione ?

Se hai problemi o domande, sentiti libero di chiedere sul canale Matrix dedicato ai traduttori .

Note per i traduttori

Politica sulle maiuscole

Il progetto darktable ha reso prioritario mettere tutto in minuscolo, il che rende la GUI difficile da leggere, specialmente per i tooltip con più frasi. Le maiuscole ancorano visivamente l’inizio delle frasi e altro testo importante, come pulsanti, controlli ecc. Non è un caso se tutte le lingue hanno finito per usarle (anche se il tedesco ha il suo modo particolare di metterle ovunque), aiutano la leggibilità che ti piaccia o meno la loro estetica.

Il codice sorgente di Ansel riutilizza la maggior parte delle etichette di darktable e aggiunge una maiuscola iniziale nella maggior parte dei punti in cui è necessaria (intestazioni dei moduli, pulsanti). Questo viene fatto da un po’ di codice che usa la funzione C g_unichar_toupper() di Gtk Glib, in modo che il testo inglese originale rimanga in minuscolo per mantenere la compatibilità con le traduzioni.

Questa correzione programmatica funziona per i caratteri non accentati, indipendentemente dalla lingua usata (stringhe predefinite in inglese, o traduzioni). Tuttavia, non funziona per i caratteri accentati iniziali, che non verranno resi maiuscoli. In questo caso, ai traduttori viene chiesto di forzare la loro traduzione a usare caratteri accentati maiuscoli iniziali ogniqualvolta siano grammaticalmente corretti nella loro lingua.

Le nuove etichette o le vecchie etichette modificate di recente (che comunque romperebbero le traduzioni) riceveranno d’ora in poi le maiuscole iniziali, nel codice sorgente (versione inglese), quindi questo dovrebbe essere progressivamente corretto.

Tradurre i termini tecnici

I termini tecnici relativi alla teoria del colore e alla colorimetria devono essere tradotti esattamente dall’inglese, con particolare attenzione perché questi termini possono esistere anche nel linguaggio comune (ovvero non tecnico) ma con un significato diverso. La Commissione Elettrotecnica Internazionale  fornisce un motore di ricerca dove puoi cercare i termini tecnici inglesi e ottenere le traduzioni accurate in diverse lingue, comprese le principali lingue europee così come l’arabo e il cinese.

Notes aux traducteurs francophones

La traduction de darktable comporte des bizarreries incompréhensibles pour quiconque utilise un ordinateur de bureau depuis plus de 10 ans. Voici une liste rapide des erreurs à corriger:

  • “set” est traduit “positionné” mais sa traduction correcte est “réglé”. C’est illogique car “settings” est correctement traduit “réglages”. Dans Ansel, on ne positionne que des masques (ou leurs nœuds de contrôle) dans le plan 2D. Le reste, ce sont des réglages.
  • “reset” est traduit “repositionné” mais sa traduction correcte est “réinitialiser”.
  • En anglais, un grand nombre de verbes ont la même graphie pour leur infinitif et leur participe-passé, voire même existent comme substantif (“set”, dans l’exemple ci-dessus, peut être traduit “réglé” ou “régler” ou comme “ensemble” sous sa forme substantivée). Si une action (pas encore effectuée) est requise, l’infinitif doit être utilisé en français. Si une action est déjà effectuée, c’est le participe-passé qui doit être employé. Les choses se corsent pour les substantifs car l’anglais ne requiert pas toujours de déterminant devant, il faut donc le déduire du contexte. À surveiller : “click” (cliquer ou clic), “type” (type ou entrer/taper), etc.
Translated from English by : Claude. In case of conflict, inconsistency or error, the English version shall prevail.