Tłumaczenie treści¶

Chociaż język angielski jest bardzo popularnym językiem wśród programistów, wielu z nich nie zna angielskiego lub nie posługuje się nim płynnie. Stanowi to problem z dostępnością dla programistów, dlatego chcemy udostępniać naszą dokumentację w jak największej liczbie języków.

Niestety, główny zespół BeeWare składa się w większości z osób posługujących się wyłącznie językiem angielskim. Potrzebujemy Państwa pomocy w tłumaczeniu naszej dokumentacji na inne języki.

Do zarządzania tłumaczeniami używamy Weblate. Weblate to narzędzie, które pozwala nam traktować każdy akapit treści w naszej dokumentacji jako listę zadań do wykonania, które możemy realizować po kolei.

Wykorzystujemy DeepL do tłumaczenia maszynowego w celu uzyskania wstępnej wersji tłumaczenia. Tłumaczenia maszynowe nie są idealne, ale zazwyczaj wystarczają jako pierwszy szkic. Oczekuje się, że tłumaczenia maszynowe będą w razie potrzeby edytowane, weryfikowane i ulepszane.

Wkład w tłumaczenia¶

Przetłumacz treść

Pierwsze kroki w tłumaczeniu¶

Jeśli chcesz wziąć udział w tłumaczeniu BeeWare, potrzebujesz konta na Weblate. Załóż nowe konto, jeśli jeszcze go nie masz, a potem daj nam znać, że chcesz pomóc w tłumaczeniu.

Istnieją dwie możliwości poinformowania nas, że chcesz pomóc w tłumaczeniach:

Jeśli korzystasz z Discorda, dołącz do serwera BeeWare i przejdź do kanału .
Jeśli nie korzystasz z Discorda, możesz utworzyć nowe zgłoszenie w repozytorium BeeWare.

W obu przypadkach proszę zostawić wiadomość zawierającą następujące informacje:

Twoja nazwa użytkownika Weblate
Język, na który planujesz przetłumaczyć treść

Gdy otrzymamy te informacje, dodamy Cię do zespołu.

Dodawanie nowego tłumaczenia¶

Jeśli język, w którym chcesz pomóc, jeszcze nie istnieje, musisz wykonać kilka dodatkowych kroków, zanim zaczniesz:

Utwórz plik /docs/mkdocs.language-code.yml, zawierający treści specyficzne dla danego języka.
Zaktualizuj tox.ini w celu uwzględnienia nowych poleceń kompilacji języka.
Zaktualizuj /docs/config.yml, aby uwzględnić język pod extra: alternate:.

Poniżej przedstawiono niezbędne zmiany na przykładzie języka niemieckiego; niemieckie tłumaczenie już istnieje; należy zastąpić odniesienia do języka niemieckiego, de, lub inne treści dla języka, który jest celem tłumaczenia.

Nowy plik konfiguracyjny MkDocs¶

Najpierw utwórz nowy plik o nazwie mkdocs.de.yml w katalogu docs, zawierający następującą treść:

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Oto, co dzieje się w tym pliku:

Ten plik dziedziczy zawartość konfiguracji z config.yml.
Wartość site_name jest tłumaczona.
Wartość site_url to adres URL witryny projektu, po którym następuje kod języka.
docs_dir powinno być kodem języka.
Wartość theme: language: powinna być kodem języka, zgodnie z specyfikacją motywu MkDocs Material. W przypadku większości języków będzie to ten sam kod języka co docs_dir, ale w przypadku niektórych (w szczególności języków z wariantami lokalnymi, takimi jak zh_CN) występują różnice.
extra: translation_type: powinno pozostać machine do momentu, gdy tłumaczenie osiągnie po raz pierwszy 100%, a wtedy powinno stać się human. Powróci do machine z human, jeśli spadnie poniżej 90%.

Aktualizacja `tox.ini`¶

Musisz wprowadzić kilka zmian w pliku tox.ini.

Dodajesz następujące informacje:

Nowa flaga środowiska kodu języka w linii nagłówka, która zaczyna się od [testenv:docs, z kodem języka poprzedzonym znakiem -, bez spacji, np. -de.
Nowe wykluczenie kodu języka dla pierwszego polecenia, które zaczyna się od !lint, poprzedzone -!, bez spacji, np. -!de.
Nowy kod języka na końcu linii zaczynającej się od translate : build_po_translations.
Nowy kod języka na końcu linii zaczynającej się od translate : update_machine_translations
Nowe polecenie, zaczynające się na przykład od de : build_md_translations dla języka niemieckiego, po innych istniejących poleceniach specyficznych dla danego języka, które dopasowują treść tych poleceń do nowego kodu języka.
Nowy kod języka na końcu linii zaczynającej się od all,serve :.

Aktualizacja `config.yml`¶

Dodaj język do config.yml, aby pojawił się on w selektorze języka w nagłówku. Znajdź sekcję zaczynającą się od extra:, a następnie zlokalizuj podsekcję zaczynającą się od alternate:. W przypadku języka niemieckiego należy dodać następujący wpis:

    - name: Deutsch
      link: /de/
      lang: de

Nazwa języka powinna być przetłumaczona na dany język. Link musi zawierać symbole /.

Nowy język jest już gotowy do rozpoczęcia tłumaczenia.

Wytyczne dotyczące tłumaczenia¶

Po dodaniu do zespołu należy zalogować się do Weblate i rozpocząć pracę nad tłumaczeniem ciągów znaków.

Tłumaczenie dosłowne a tłumaczenie oddające sens¶

Ważniejsze jest zachowanie tonu tekstu angielskiego niż dążenie do dosłownego tłumaczenia. Staramy się, aby nasze treści były przyjazne i nieco potoczne; postaraj się zachować ten charakter w swoich tłumaczeniach.

Jeśli tekst angielski zawiera mocne idiomy, nie czuj się zobowiązany do ich zachowania, jeśli w Twoim języku istnieje analogiczne wyrażenie, które sprawdzi się równie dobrze. Jeśli termin lub fraza w tekście angielskim jest szczególnie idiomatyczna lub slangowa, nie wahaj się poinformować nas, że powinniśmy rozważyć wprowadzenie zmiany. Nawet dla osób posługujących się językiem angielskim idiomy i slang mogą stanowić trudność. Czasami musimy zmienić tekst angielski, aby był bardziej zrozumiały zarówno dla tłumaczy, jak i czytelników.

Czy powinienem to przetłumaczyć?¶

Następujące elementy nie powinny być tłumaczone ani aktualizowane:

Polecenia. Na przykład w zdaniu „You should run `briefcase create`” należy przetłumaczyć tylko „You should run”.
Przestrzenie nazw, takie jak nazwy klas, metod lub atrybutów.
Adresy URL linków. Standardowe linki Markdown powinny pojawiać się w Weblate jako [Link text]{1}, gdzie 1 to pozycja linku w ciągu znaków w odniesieniu do innych możliwych linków. Jeśli pełny adres URL jest zawarty w ciągu znaków jako [Link text](https://example.com), adres URL powinien zostać pominięty podczas tłumaczenia.
Linki referencyjne zawierające nazwy klas, metod lub atrybutów. Należy je pozostawić bez zmian, łącznie z znakami backtick. Żadna część przykładowego linku pokazanego tutaj nie zostanie przetłumaczona.
```
[`Class.attribute`][Class.attribute]
```
Treść linku odsyłającego. Na przykład link-content zostanie pominięte w poniższym przykładzie:
```
[Link text][link-content]
```
Dyrektywy Jinja. Jest to dowolna treść ujęta w dwie pary dopasowanych nawiasów klamrowych lub dopasowaną parę pojedynczych nawiasów klamrowych z znakami procentowymi na każdym końcu. Uwaga: Umieszczenie tutaj przykładu składni powoduje, że wtyczka Makra próbuje ją renderować; przykłady można znaleźć w dokumentacji Makr.
Niestandardowe kotwice. Znajdują się one po nagłówkach lub nad niektórymi treściami i mają format { #anchor }.
Składnia upomnienia. W poniższym przykładzie słowo „upomnienie” nie powinno być tłumaczone. Dotyczy to wszystkich rodzajów upomnień, w tym uwag, ostrzeżeń itp. Informacje na temat tłumaczenia pozostałej części treści znajdują się w następnej sekcji.
```
/// admonition | Page Title

Content.

///
```
Backticks. Powinny pozostać jako backticks; służą do formatowania zarówno kodu wbudowanego, jak i bloków kodu.
Składnia służąca do włączania treści zewnętrznych. Jest to wszystko, co znajduje się w tym samym wierszu co -8<-, lub w wierszach pomiędzy dwoma -8<- w oddzielnych wierszach.

Następujące elementy powinny zostać przetłumaczone:

Tekst linku. W składni linku tekst znajduje się przed adresem URL i jest ujęty w nawiasy, tak jak w [Link text](URL). Standardowe linki Markdown powinny pojawiać się w Weblate jako [Link text]{1}, gdzie 1 jest pozycją linku w ciągu znaków w odniesieniu do innych możliwych linków.
Tekst linku referencyjnego. Na przykład Link text zostanie przetłumaczone w następujący sposób:
```
[Link text][link-content]
```
Tytuły i treść upomnień. W poprzednim przykładzie upomnienia należy przetłumaczyć „Tytuł strony” i „Treść”.

Weblate¶

Do tłumaczenia treści używamy Weblate. Kiedy dodajemy nowe tłumaczenie, używamy DeepL do tłumaczenia maszynowego, aby uzyskać wstępną wersję tłumaczenia. Oznacza to, że zazwyczaj tłumaczona treść jest już przetłumaczona maszynowo. Oczekuje się, że jako tłumacz przejrzysz, edytujesz i poprawisz istniejące tłumaczenie maszynowe.

Weblate przetwarza wszystko na zasadzie ciągów znaków. Gromadzi zmiany i co kilka godzin przesyła zbiorcze zatwierdzenie wszystkich ciągów znaków, które uległy zmianie w tym okresie. Dlatego też może minąć kilka godzin, zanim zmiany pojawią się na stronie internetowej, ale można oczekiwać, że aktualizacja pojawi się w ciągu czterech godzin.

Jeśli po upływie tego czasu zmiany nadal nie zostaną wyświetlone, prawdopodobną przyczyną jest błąd znaczników, powodujący niepowodzenie kompilacji dokumentacji dla tego języka. Każdy problem ze znacznikami w dowolnym ciągu znaków blokuje publiczne udostępnienie całego tłumaczenia. Możesz śledzić stronę kompilacji dla swojego języka, aby sprawdzić, czy kompilacja zakończyła się powodzeniem. Link jest sformatowany podobnie do tego linku do francuskiej strony kompilacji https://app.readthedocs.org/projects/beewareorg/; zmień kod języka na swój język, aby wyświetlić odpowiednią stronę kompilacji. Wyświetli to stan najnowszej kompilacji witryny. Jeśli kompilacja nie powiedzie się, sprawdź dziennik kompilacji i spróbuj zidentyfikować źródło problemu.