Ansel gebruikt Gettext  om alle onderdelen van het project te vertalen:

  • De softwareapplicatie (geschreven in C),
  • De website (Hugo-templates en Markdown-inhoud),
  • De documentatie/gebruikershandleiding, als module in de website ingevoegd (ook Hugo-templates en Markdown-inhoud).

Dit zorgt ervoor dat dezelfde workflow kan worden gebruikt om alle bestanden te vertalen, maar ook dat sommige vertaalde tekenreeksen kunnen worden gedeeld (bijvoorbeeld kunnen de vertaalde GUI-besturingselementen uit de applicaties direct in de documentatie worden ingevoegd).

Organisatie van vertaalbestanden

De broncode van de website, documentatie en software bevat telkens een directe po/-submap, die het volgende bevat:

  • één .pot-bestand dat alle beschikbare, vertaalbare tekenreeksen in hun oorspronkelijke taal (in het Engels) bevat,
  • veel .po-bestanden die vertaalbare tekenreeksen in hun oorspronkelijke taal koppelen aan hun vertaling (één taal per bestand).

Vertaalbestanden worden allemaal genoemd volgens de conventie language-code.po. Bijvoorbeeld:

  • voor Duits,
    • is de softwarevertaling de.po,
    • is de websitevertaling content.de.po,
    • is de documentatievertaling content.de.po,
  • voor Braziliaans Portugees,
    • is de softwarevertaling pt_BR.po,
    • is de websitevertaling content.pt_br.po,
    • is de documentatievertaling content.pt_br.po.

Vertalen wanneer je geen CLI/Git kunt gebruiken

Je moet het relevante .po-bestand voor jouw taal opzoeken voor het onderdeel van het project dat je wilt vertalen:

  1. Download dit bestand en open het met Poedit ,
  2. Breng de correcties en bewerkingen aan die je nodig hebt,
  3. Voeg je naam toe in een commentaar bij de tekenreeksen die je vertaalt als je op de pagina vermeld wilt worden :
    • Automatisch vertaalde tekenreeksen bevatten daar TRANSLATOR ChatGPT; zodra je die tekenreeksen hebt geverifieerd, verwijder je deze regel,
    • Voeg vervolgens op een nieuwe regel een commentaar toe met TRANSLATOR Your Name. Behoud eventuele andere (niet-ChatGPT) bijdragers.
  4. Sla het bestand op en:
    • Alternatief 1 (makkelijker voor bijdrager, meer stappen voor beheerder): zet het op mijn privécloud ,
    • Alternatief 2 (meer stappen voor bijdrager, makkelijker voor beheerder): commit het met Git en open een pull request tegen de juiste Github-repository.

Vertalen voor gevorderde gebruikers

Dit werkt het .pot-bestand bij met behulp van de broncode van het project. Je moet Git geïnstalleerd hebben en Hugo 0.146  op je computer geïnstalleerd hebben.

  1. Kloon de broncode van het relevante project:
    • de software :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • de website :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • de documentatie :
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Later werk je de repository bij met :
    1$ git pull
  2. Werk het .pot-bestand en alle .po-bestanden bij vanuit de broncode (deze stap werkt hetzelfde voor alle 3 de projecten):
    1$ sh tools/update-translations.sh
  3. Vertaal het relevante .po-bestand met Poedit of rechtstreeks in een teksteditor (zie Vertalen wanneer je geen CLI/Git kunt gebruiken),
  4. Test & controleer je vertaling :
    • Voor de software moet je Ansel bouwen op je besturingssysteem. Zie de documentatie.
    • Voor de website en de documentatie kun je uitvoeren :
      1sh build-modules.sh
2hugo
    Let op kritieke fouten van po4a, vooral bij niet-overeenkomende \n-tekens, en op fouten van Hugo, vooral wat betreft de syntaxis van shortcodes.
  5. Ruim voor de website en documentatie de vertaalde Markdown-bestanden op (automatisch gegenereerd door po4a met behulp van het .po-bestand) voordat je commit, met :
    1sh tools/build-translations.sh --remove
  6. Commit alle .pot- en .po-bestanden en open een pull request tegen de relevante Github-repository. Commit nooit vertaalde .md-bestanden (Markdown).

Afbeeldingen vertalen

Het volgende geldt alleen voor de website en documentatie.

Afbeeldingen kunnen ook worden vertaald, bijvoorbeeld schermafbeeldingen van de applicatie. Afbeeldingen worden opgeslagen in de map assets/ als ze op meerdere pagina’s worden hergebruikt (globale assets), anders worden ze opgeslagen in dezelfde map als het Markdown-bestand dat ze gebruikt (lokale assets). Of het nu globaal of lokaal is, het vertaalproces is hetzelfde, alleen de basismap verandert.

Als je bijvoorbeeld de assets/screenshot.jpg wilt vertalen voor de taal LANG (wat de ISO-code van de taal is, zoals de, nl, pt_br, zn_cn, enz.):

  1. voeg een nieuw afbeeldingsbestand assets/screenshot.LANG.jpg toe aan de documentatie- of website-Git-repository en commit het,
  2. zoek in de content.LANG.po de vermelding met de Markdown-tag voor de oorspronkelijke afbeelding, die er ongeveer zo uitziet: ![alt text](screenshot.jpg),
  3. vertaal de Markdown-tag door de URL van de afbeelding te vervangen, zoals ![translated alt text](screenshot.LANG.jpg,
  4. sla het content.LANG.po-bestand op en commit het,
  5. maak een pull request tegen de Ansel-website- of Ansel-docs-repository.

Automatische tools en hulpscripts

Documentatievertaling initialiseren met die van de software

Omdat de documentatie en de software dezelfde tekenreeksen voor de GUI-besturingselementen delen, kun je de documentatietekenreeksen lui initialiseren vanuit die van de software als ze exact overeenkomen (inclusief hoofdlettergebruik). Hiervoor is een Python-interpreter en het regex-pakket nodig (installeer met pip install -U regex). Vanuit de broncode van de documentatie kun je aanroepen :

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

Documentatie en website automatisch vertalen met ChatGPT

ChatGPT-4o doet het redelijk goed bij het vertalen van Markdown-opgemaakte tekst uit het Engels, hoewel niet in elke taal. Je hebt een privé-API-sleutel nodig die je in de map van de documentatie of website opslaat in een .chatgpt.api_key-bestand. Bovendien zijn aanroepen naar de ChatGPT API niet gratis, en met de minimale betaling van 5 US$ krijg je de website ongeveer volledig vertaald in 4 talen.

Het alles-in-één-script kan worden aangeroepen met :

1$ sh auto-translate.sh LANG

waarbij LANG de doeltaalcode is (de, fr, pt_br, enz.). Dit verwerkt de vertaling in batches van 90 tot 120 tekenreeksen om te voldoen aan de beperkingen en drempelwaarden van de ChatGPT API. Dit zal :

  • het oorspronkelijke po/content.LANG.po-bestand parseren en de te vertalen batch exporteren naar een tijdelijk po/content.LANG.txt-bestand,
  • het po/content.LANG.txt-bestand naar ChatGPT sturen en het antwoord ontvangen in po/content.LANG.generated.txt
  • de meest voorkomende opmaakinconsistenties die ChatGPT kan introduceren corrigeren en de vertalingen terug in po/content.LANG.po injecteren,
  • vertaalde Markdown-bestanden bouwen (volgens de naamconventie page.LANG.md),
  • de website bouwen met Hugo.

Als al deze stappen zonder fouten worden voltooid, kun je het script opnieuw uitvoeren om de volgende batch te verwerken totdat het klaar is. Als er fouten worden getoond, moet je ze corrigeren. We voeren bij elke aanroep slechts één batch uit om de gebruiker de gelegenheid te geven fouten te vinden zolang er niet te veel wijzigingen te inspecteren zijn.

Veelvoorkomende fouten:

  • er wordt niets vertaald : controleer het antwoord van ChatGPT in po/content.LANG.generated.txt; soms is het niet in staat zijn opdracht te begrijpen. Je kunt het opnieuw proberen; soms werkt het bij de 3e aanroep. Maar vaak valt er niets te doen en kunnen sommige talen/tekenreeksen helemaal niet worden vertaald.
  • bij het bouwen van de website met Hugo kan een shortcode niet worden gevonden. Dit komt doordat shortcodes als volgt worden gedeclareerd : {{< shortcode_name >}}. Soms probeert ChatGPT shortcode_name te vertalen en werkt de shortcode niet meer. De oplossing is de Engelse naam voor de shortcode en zijn attributen terug te zetten,
  • hetzelfde geldt voor Mermaid -grafieken: ChatGPT kan proberen commando’s en eigenschappen te vertalen die niet vertaald mogen worden,
  • oorspronkelijke tekenreeksen eindigen met het newline-teken \n en de vertaalde tekenreeksen niet (of andersom). Het script probeert dat op te schonen, maar sommige uitzonderingsgevallen worden niet afgehandeld. Oorspronkelijke tekenreeksen msgid en hun vertaling msgstr in het .po-bestand moeten hetzelfde aantal \n-tekens op dezelfde plaats hebben,
  • onjuist ge-escapete dubbele aanhalingstekens : de Gettext-tekenreeksen msgid en msgstr moeten aan elk uiteinde van de tekenreeks worden begrensd door niet-ge-escapete dubbele aanhalingstekens ". Elk ander dubbel aanhalingsteken binnen de Gettext-tekenreeks moet worden ge-escaped met \".

De beste manier om fouten te corrigeren is het relevante .po-bestand in een teksteditor te openen. Als je de fout niet kunt vinden en oplossen, kun je proberen het bestand in Poedit te openen, maar bij het opslaan wist het meestal de foutieve tekenreeksen volledig zonder ze te corrigeren, zodat de vertaling helemaal opnieuw moet worden begonnen.

Vertaalde Markdown-bestanden bouwen

Voor de website en documentatie verzorgt Hugo  de vertalingen van een gegeven pagina new_page.md met de naamconventie new_page.LANG.md, waarbij LANG de taalcode is. Hugo ondersteunt van nature het handmatig schrijven van deze vertaalde bestanden in dezelfde map als hun origineel, maar hier genereren we ze met behulp van het .po-vertaalbestand en het programma po4a. De scripts build-modules.sh en tools/auto-translate.sh handelen dit intern af, maar mogelijk wil je die bestanden handmatig genereren :

  1. Werk de .pot- en .po-bestanden bij met de broncode :
    1$ sh tools/update-translations.sh
  2. Maak de vertaalde .md-bestanden aan :
    1$ sh tools/build-translations.sh --add
  3. Ruim de vertaalde .md-bestanden op :
    1$ sh tools/build-translations.sh --remove

Het is belangrijk om de vertaalde .md-bestanden nooit met Git te committen, omdat ze alleen door dat script opnieuw worden gegenereerd bij het bouwen van de website. Dit is alleen voor de netheid van de repository, er is geen technisch nadeel. Het opschonen van de vertaalde .md-bestanden voor het committen voorkomt fouten.

Verdwaald in de vertaling ?

Als je problemen of vragen hebt, stel ze gerust in het speciale Matrix-kanaal voor vertalers .

Opmerkingen voor vertalers

Beleid ten aanzien van hoofdletters

Het darktable-project maakte er een prioriteit van om alles in kleine letters te zetten, wat de GUI moeilijk leesbaar maakt, vooral voor tooltips met meerdere zinnen. Hoofdletters verankeren visueel het begin van zinnen en andere belangrijke tekst, zoals knoppen, besturingselementen enz. Het is geen toeval dat alle talen zijn geconvergeerd naar het gebruik ervan (al heeft het Duits zijn eigen manier om ze overal te plaatsen); ze bevorderen de leesbaarheid, of je hun esthetiek nu mooi vindt of niet.

De broncode van Ansel hergebruikt de meeste labels van darktable en voegt op de meeste plaatsen waar ze nodig zijn een beginhoofdletter toe (moduleheaders, knoppen). Dit gebeurt met een stukje code dat de C-functie g_unichar_toupper() uit Gtk Glib gebruikt, zodat de oorspronkelijke Engelse tekst in kleine letters blijft om compatibiliteit met vertalingen te behouden.

Deze programmatische oplossing werkt voor niet-geaccentueerde tekens, ongeacht de gebruikte taal (standaardtekenreeksen in het Engels, of vertalingen). Ze werkt echter niet voor geaccentueerde begintekens, die geen hoofdletter krijgen. In dat geval wordt vertalers gevraagd hun vertaling te forceren om geaccentueerde beginhoofdletters te gebruiken wanneer die grammaticaal correct zijn in hun taal.

Nieuwe labels of onlangs gewijzigde oude labels (die vertalingen toch zouden breken) krijgen voortaan beginhoofdletters in de broncode (Engelse versie), dus dit zou geleidelijk verholpen moeten worden.

Technische termen vertalen

Technische termen met betrekking tot kleurtheorie en colorimetrie moeten exact vanuit het Engels worden vertaald, met extra zorg omdat deze termen ook in de omgangstaal (oftewel niet-technisch) kunnen bestaan, maar met een andere betekenis. De International Electrotechnical Commission  biedt een zoekmachine waarmee je de Engelse technische termen kunt opzoeken en de accurate vertalingen in verschillende talen kunt krijgen, waaronder de belangrijkste Europese talen, evenals Arabisch en Chinees.

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.