Ansel używa Gettext  do tłumaczenia wszystkich części projektu:

  • Aplikacji (napisanej w C),
  • Strony internetowej (szablony Hugo i treść w Markdown),
  • Dokumentacji/podręcznika użytkownika, dołączonego do strony jako moduł (również szablony Hugo i treść w Markdown).

Dzięki temu ten sam przepływ pracy może służyć do tłumaczenia wszystkich plików, a niektóre przetłumaczone ciągi znaków można współdzielić (na przykład przetłumaczone elementy interfejsu z aplikacji można wstawić bezpośrednio do dokumentacji).

Organizacja plików tłumaczeń

Kod źródłowy strony internetowej, dokumentacji i oprogramowania zawiera bezpośredni podfolder po/, który zawiera:

  • jeden plik .pot, który przechowuje wszystkie dostępne, przetłumaczalne ciągi znaków w ich oryginalnym języku (po angielsku),
  • wiele plików .po, które łączą przetłumaczalne ciągi znaków w ich oryginalnym języku z ich tłumaczeniem (jeden język na plik).

Wszystkie pliki tłumaczeń są nazywane zgodnie z konwencją language-code.po. Na przykład:

  • dla niemieckiego,
    • tłumaczenie oprogramowania to de.po,
    • tłumaczenie strony to content.de.po,
    • tłumaczenie dokumentacji to content.de.po,
  • dla portugalskiego brazylijskiego,
    • tłumaczenie oprogramowania to pt_BR.po,
    • tłumaczenie strony to content.pt_br.po,
    • tłumaczenie dokumentacji to content.pt_br.po.

Tłumaczenie, gdy nie możesz używać CLI/Git

Musisz odnaleźć odpowiedni plik .po dla swojego języka, dla tej części projektu, którą chcesz przetłumaczyć:

  1. Pobierz ten plik i otwórz go w Poedit ,
  2. Wprowadź potrzebne poprawki i zmiany,
  3. Dodaj swoje imię w komentarzu przy ciągach, które tłumaczysz, jeśli chcesz zostać wymieniony na stronie:
    • Ciągi przetłumaczone automatycznie będą tam miały TRANSLATOR ChatGPT; po zweryfikowaniu tych ciągów usuń tę linię,
    • Następnie dodaj w nowej linii komentarz zawierający TRANSLATOR Twoje Imię. Zachowaj innych współtwórców (spoza ChatGPT), jeśli tacy są.
  4. Zapisz plik i:
    • Alternatywa 1 (łatwiejsza dla współtwórcy, więcej kroków dla opiekuna): umieść go na moim prywatnym cloudzie ,
    • Alternatywa 2 (więcej kroków dla współtwórcy, łatwiejsza dla opiekuna): zatwierdź go za pomocą Git i otwórz pull request w odpowiednim repozytorium Github.

Tłumaczenie dla zaawansowanych użytkowników

Spowoduje to aktualizację pliku .pot na podstawie kodu źródłowego projektu. Musisz mieć zainstalowany Git oraz Hugo 0.146  na swoim komputerze.

  1. Sklonuj kod źródłowy odpowiedniego projektu:
    • oprogramowanie:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel.git
3$ cd ansel
    • strona internetowa:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-website.git
3$ cd ansel-website
    • dokumentacja:
      1$ git clone --depth 1 \
2  https://github.com/aurelienpierreeng/ansel-doc.git
3$ cd ansel-doc
    Później zaktualizujesz repozytorium za pomocą:
    1$ git pull
  2. Zaktualizuj plik .pot i wszystkie pliki .po na podstawie kodu źródłowego (ten krok działa tak samo dla wszystkich 3 projektów):
    1$ sh tools/update-translations.sh
  3. Przetłumacz odpowiedni plik .po za pomocą Poedit lub bezpośrednio w edytorze tekstu (zobacz Tłumaczenie, gdy nie możesz używać CLI/Git),
  4. Przetestuj i sprawdź swoje tłumaczenie:
    • W przypadku oprogramowania musisz zbudować Ansel na swoim systemie operacyjnym. Zobacz dokumentację.
    • W przypadku strony i dokumentacji możesz uruchomić:
      1sh build-modules.sh
2hugo
    Zwróć uwagę na wszelkie krytyczne błędy z po4a, zwłaszcza dotyczące niezgodnych znaków \n, oraz błędy z Hugo, zwłaszcza dotyczące składni shortcode’ów.
  5. W przypadku strony i dokumentacji przed zatwierdzeniem wyczyść przetłumaczone pliki Markdown (generowane automatycznie przez po4a na podstawie pliku .po), używając:
    1sh tools/build-translations.sh --remove
  6. Zatwierdź wszystkie pliki .pot i .po oraz otwórz pull request w odpowiednim repozytorium Github. Nigdy nie zatwierdzaj przetłumaczonych plików .md (Markdown).

Tłumaczenie obrazów

Poniższe dotyczy wyłącznie strony internetowej i dokumentacji.

Obrazy również można tłumaczyć, na przykład zrzuty ekranu aplikacji. Obrazy są przechowywane w folderze assets/, jeśli są używane ponownie na kilku stronach (zasoby globalne); w przeciwnym razie są przechowywane w tym samym folderze co plik Markdown, który ich używa (zasoby lokalne). Niezależnie od tego, czy są globalne, czy lokalne, proces tłumaczenia jest taki sam, zmienia się tylko folder bazowy.

Jeśli na przykład chcesz przetłumaczyć assets/screenshot.jpg dla języka LANG (który jest kodem ISO języka, jak de, nl, pt_br, zn_cn itd.):

  1. dodaj i zatwierdź nowy plik obrazu assets/screenshot.LANG.jpg w repozytorium Git dokumentacji lub strony,
  2. w pliku content.LANG.po odnajdź wpis zawierający znacznik Markdown dla oryginalnego obrazu, który będzie wyglądał mniej więcej tak: ![alt text](screenshot.jpg),
  3. przetłumacz znacznik Markdown, zastępując adres URL obrazu, np. ![translated alt text](screenshot.LANG.jpg,
  4. zapisz i zatwierdź plik content.LANG.po,
  5. utwórz pull request w repozytorium strony Ansel lub dokumentacji Ansel.

Narzędzia automatyczne i skrypty pomocnicze

Inicjowanie tłumaczenia dokumentacji na podstawie tłumaczenia oprogramowania

Ponieważ dokumentacja i oprogramowanie współdzielą te same ciągi znaków dla elementów interfejsu, możesz wygodnie zainicjować ciągi dokumentacji na podstawie tych z oprogramowania, jeśli dokładnie się zgadzają (włącznie z wielkością liter). Wymaga to interpretera Pythona oraz pakietu regex (instalacja przez pip install -U regex). Z poziomu kodu źródłowego dokumentacji możesz wywołać:

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

Automatyczne tłumaczenie dokumentacji i strony za pomocą ChatGPT

ChatGPT-4o całkiem dobrze radzi sobie z tłumaczeniem tekstu sformatowanego w Markdown z angielskiego, choć nie w każdym języku. Będziesz potrzebować prywatnego klucza API, który należy zapisać w folderze dokumentacji lub strony w pliku .chatgpt.api_key. Ponadto wywołania API ChatGPT nie są darmowe, a minimalna płatność 5 US$ pozwoli mniej więcej na pełne przetłumaczenie strony na 4 języki.

Skrypt wszystko-w-jednym można wywołać za pomocą:

1$ sh auto-translate.sh LANG

gdzie LANG to kod języka docelowego (de, fr, pt_br itd.). Spowoduje to przetworzenie tłumaczenia w partiach po 90 do 120 ciągów znaków, aby dostosować się do ograniczeń i limitów API ChatGPT. Spowoduje to:

  • przeanalizuje oryginalny plik po/content.LANG.po i wyeksportuje partię do przetłumaczenia do tymczasowego pliku po/content.LANG.txt,
  • wyśle plik po/content.LANG.txt do ChatGPT i otrzyma odpowiedź w po/content.LANG.generated.txt
  • naprawi najczęstsze niespójności formatowania, które ChatGPT może wprowadzić, i wstrzyknie tłumaczenia z powrotem do po/content.LANG.po,
  • zbuduje przetłumaczone pliki Markdown (zgodnie z konwencją nazewnictwa page.LANG.md),
  • zbuduje stronę za pomocą Hugo.

Jeśli wszystkie te kroki zakończą się bez błędów, możesz uruchomić skrypt ponownie, aby przetworzyć kolejną partię, aż do ukończenia. Jeśli pojawią się błędy, musisz je naprawić. Uruchamiamy tylko jedną partię przy każdym wywołaniu, aby dać użytkownikowi możliwość znalezienia błędów, gdy nie ma jeszcze zbyt wielu zmian do sprawdzenia.

Częste błędy:

  • nic nie zostanie przetłumaczone: sprawdź odpowiedź ChatGPT w po/content.LANG.generated.txt, czasami nie jest w stanie zrozumieć swojego zadania. Możesz spróbować ponownie, czasami udaje się za 3. razem. Ale często nie da się nic zrobić i niektórych języków/ciągów w ogóle nie da się przetłumaczyć.
  • podczas budowania strony za pomocą Hugo nie można znaleźć jakiegoś shortcode’a. Dzieje się tak, ponieważ shortcode’y są deklarowane w ten sposób: {{< shortcode_name >}}. Czasami ChatGPT próbuje przetłumaczyć shortcode_name i shortcode znowu nie działa. Rozwiązaniem jest przywrócenie angielskiej nazwy shortcode’a i jego atrybutów,
  • to samo dotyczy wykresów Mermaid , ChatGPT może próbować tłumaczyć polecenia i właściwości, których nie należy tłumaczyć,
  • oryginalne ciągi kończą się znakiem nowej linii \n, a przetłumaczone nie (lub odwrotnie). Skrypt próbuje to naprawić, ale niektóre przypadki brzegowe nie są obsługiwane. Oryginalne ciągi msgid i ich tłumaczenie msgstr w pliku .po powinny mieć taką samą liczbę znaków \n w tym samym miejscu,
  • nieprawidłowo zabezpieczone cudzysłowy: ciągi Gettext msgid i msgstr powinny być ograniczone niezabezpieczonym cudzysłowem " na każdym końcu ciągu. Każdy inny cudzysłów wewnątrz ciągu Gettext powinien być zabezpieczony za pomocą \".

Najlepszym sposobem na naprawienie błędów jest otwarcie odpowiedniego pliku .po w edytorze tekstu. Jeśli nie możesz znaleźć błędu i go rozwiązać, możesz spróbować otworzyć plik w Poedit, ale podczas zapisywania zwykle całkowicie usunie on wadliwe ciągi bez ich naprawy, więc tłumaczenie trzeba będzie zacząć od nowa.

Budowanie przetłumaczonych plików Markdown

W przypadku strony i dokumentacji Hugo  obsługuje tłumaczenia danej strony new_page.md przy użyciu konwencji nazewnictwa new_page.LANG.md, gdzie LANG to kod języka. Hugo natywnie obsługuje ręczne zapisywanie tych przetłumaczonych plików w tym samym folderze co ich oryginał, jednak tutaj generujemy je za pomocą pliku tłumaczeń .po i programu po4a. Skrypty build-modules.sh i tools/auto-translate.sh obsługują to wewnętrznie, ale możesz chcieć wygenerować te pliki ręcznie:

  1. Zaktualizuj pliki .pot i .po na podstawie kodu źródłowego:
    1$ sh tools/update-translations.sh
  2. Utwórz przetłumaczone pliki .md:
    1$ sh tools/build-translations.sh --add
  3. Wyczyść przetłumaczone pliki .md:
    1$ sh tools/build-translations.sh --remove

Ważne, aby nigdy nie zatwierdzać przetłumaczonych plików .md za pomocą Git, ponieważ są one regenerowane wyłącznie przez ten skrypt podczas budowania strony. Służy to jedynie porządkowi w repozytorium, nie ma żadnej technicznej wady. Wyczyszczenie przetłumaczonych plików .md przed zatwierdzeniem zapobiega pomyłkom.

Zagubieni w tłumaczeniu?

Jeśli masz problemy lub pytania, śmiało zapytaj na dedykowanym kanale tłumaczy na Matrix .

Uwagi dla tłumaczy

Zasady dotyczące wielkich liter

Projekt darktable postawił sobie za priorytet zapisywanie wszystkiego małymi literami, co utrudnia czytanie interfejsu, zwłaszcza w przypadku podpowiedzi składających się z kilku zdań. Wielkie litery wizualnie zakotwiczają początek zdań oraz inny ważny tekst, jak przyciski, elementy sterujące itd. To nie przypadek, że wszystkie języki zbiegły się do ich używania (choć niemiecki ma swój szczególny sposób umieszczania ich wszędzie) — poprawiają one czytelność, niezależnie od tego, czy podoba ci się ich estetyka, czy nie.

Kod źródłowy Ansel wykorzystuje ponownie większość etykiet z darktable i dodaje początkową wielką literę w większości miejsc, gdzie jest ona potrzebna (nagłówki modułów, przyciski). Odbywa się to za pomocą fragmentu kodu wykorzystującego funkcję C g_unichar_toupper() z Gtk Glib, tak że oryginalny angielski tekst pozostaje zapisany małymi literami, aby zachować zgodność z tłumaczeniami.

Ta programowa poprawka działa dla znaków bez akcentów, niezależnie od używanego języka (domyślne ciągi po angielsku lub tłumaczenia). Nie działa jednak dla początkowych znaków z akcentami, które nie zostaną zapisane wielką literą. W takim przypadku prosimy tłumaczy o wymuszenie w tłumaczeniu używania początkowych wielkich liter z akcentami, o ile jest to poprawne gramatycznie w ich języku.

Nowe etykiety lub stare etykiety niedawno zmienione (co i tak zepsułoby tłumaczenia) będą odtąd otrzymywać początkowe wielkie litery w kodzie źródłowym (wersji angielskiej), więc powinno to być stopniowo naprawiane.

Tłumaczenie terminów technicznych

Terminy techniczne związane z teorią barw i kolorymetrią należy tłumaczyć dokładnie z angielskiego, ze szczególną ostrożnością, ponieważ terminy te mogą występować również w języku potocznym (czyli nietechnicznym), ale z innym znaczeniem. Międzynarodowa Komisja Elektrotechniczna  udostępnia wyszukiwarkę, w której możesz wyszukać angielskie terminy techniczne i uzyskać dokładne tłumaczenia w różnych językach, w tym w głównych językach europejskich, a także arabskim i chińskim.

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.