.po vs .mo vs .pot: Wyjaśnienie plików tłumaczeniowych WordPress

Otwierasz folder languages motywu WordPress i znajdujesz trzy pliki, które wyglądają niemal identycznie: twentytwentyfour.pot, twentytwentyfour-de_DE.po i twentytwentyfour-de_DE.mo. Ten sam motyw, ten sam język, trzy różne rozszerzenia. Który z nich edytujesz? Który z nich WordPress faktycznie ładuje? I dlaczego edytowanie niewłaściwego powoduje, że Twoje tłumaczenia cicho znikają?

Jeśli kiedykolwiek zastanawiałeś się, który plik ma znaczenie w dyskusji plików po vs mo, nie jesteś sam. Te trzy rozszerzenia stanowią podstawę każdej przetłumaczonej witryny WordPress, jednak różnica między nimi wprawia w zakłopotanie zarówno początkujących, jak i doświadczonych programistów. Edytuj niewłaściwy plik, a Twoi niemieccy odwiedzający nadal będą widzieć angielski. Edytuj właściwy, ale pomiń jeden krok, a nic się również nie zmieni.

Ten przewodnik wyjaśnia dokładnie, czym są pliki .pot, .po i .mo, jak się ze sobą wiążą w ramach przepływu pracy GNU Gettext, gdzie znajdują się w WordPressie i dlaczego nigdy nie powinieneś otwierać pliku .mo w edytorze tekstu. Na koniec będziesz wiedział, którego pliku dotykać, a którego zostawić w spokoju.

Czym są pliki .pot, .po i .mo?

W skrócie: plik .pot to pusty szablon, plik .po to Twoje edytowalne tłumaczenie, a plik .mo to skompilowany plik binarny, który WordPress odczytuje w czasie działania. Tworzą one łańcuch, a każde ogniwo ma dokładnie jedno zadanie.

Wszystkie te trzy formaty pochodzą z GNU Gettext, systemu lokalizacji, na którym polegają WordPress, Drupal oraz tysiące projektów PHP i C. Gettext oddziela ciągi źródłowe, które pisze programista, od tłumaczeń, które dostarcza tłumacz, dzięki czemu ta sama baza kodu może komunikować się w dziesiątkach języków bez dotykania ani jednej linii PHP.

Pomyśl o tym jak o karcie przepisu. Plik .pot to pusta karta z miejscami na składniki, ale bez ilości. Plik .po to karta wypełniona dla jednego konkretnego dania. Plik .mo to zalaminowana, skanowalna maszynowo kopia, której kuchnia faktycznie używa podczas serwowania. Piszesz na papierowej karcie; nigdy nie bazgrzesz na zalaminowanej.

Plik .pot: Szablon główny

Plik .pot (Portable Object Template) zawiera każdy ciąg znaków do przetłumaczenia w motywie lub wtyczce, z pustymi miejscami na tłumaczenia. Jest to główna lista, którą programiści dostarczają, aby tłumacze dokładnie wiedzieli, co należy przetłumaczyć. Linie msgstr są puste, ponieważ nie wybrano jeszcze żadnego języka.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr ""

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr ""

Zauważ pusty msgstr "". Plik .pot to szablon, a nie tłumaczenie. Kopiujesz go raz dla każdego języka i wypełniasz puste miejsca. Rzadko edytujesz plik .pot ręcznie; jest on ponownie generowany z kodu źródłowego za każdym razem, gdy zmieniają się ciągi znaków.

Plik .po: Twoje edytowalne tłumaczenie

Plik .po (Portable Object) to kopia pliku .pot z wypełnionymi liniami msgstr dla jednego języka. To jest plik, który faktycznie edytują tłumacze i programiści. Jest to plik tekstowy, czytelny dla człowieka i przyjazny dla kontroli wersji.

#: includes/checkout.php:42
msgid "Add to Cart"
msgstr "In den Warenkorb"

#: includes/account.php:108
msgid "Your order has been shipped to %s"
msgstr "Ihre Bestellung wurde an %s versandt"

msgid to oryginalny angielski ciąg źródłowy i nigdy nie może się zmienić. msgstr to Twoje tłumaczenie. %s to placeholder, który musi pozostać nietknięty w tłumaczeniu — pominięcie go lub zmiana kolejności jest najczęstszą przyczyną zepsutych układów, co szczegółowo omawiamy w artykule jak tłumaczyć pliki PO bez uszkadzania zmiennych kodu.

Plik .mo: Skompilowany plik binarny

Plik .mo (Machine Object) to skompilowana, binarna wersja Twojego pliku .po. WordPress nie potrafi efektywnie odczytywać plików .po w czasie działania, dlatego ładuje zamiast nich wstępnie skompilowany plik .mo. Otworzenie pliku .mo w edytorze tekstu pokazuje nieczytelne bajty — jest przeznaczony dla maszyn, nie dla ludzi.

Gdy WordPress wywołuje load_textdomain() lub load_theme_textdomain(), szuka pliku .mo, analizuje jego binarną tabelę haszującą i na bieżąco zamienia każdy msgid na pasujący msgstr. Ten binarny format sprawia, że wyszukiwania są szybkie nawet na stronach z tysiącami ciągów znaków.

Jak trzy pliki są ze sobą powiązane w przepływie pracy Gettext?

Tworzą jednokierunkowy potok: kod źródłowy staje się plikiem .pot, plik .pot staje się plikiem .po dla danego języka, a każdy plik .po kompiluje się do .mo. Tłumaczenia zawsze płyną w dół.

Oto pełny cykl życia w kolejności:

1. Programista owija ciągi znaków widoczne dla użytkownika w funkcje Gettext, takie jak __() i _e(), w kodzie źródłowym PHP.
2. Narzędzie skanujące odczytuje źródło i generuje szablon .pot zawierający każdy owinięty ciąg znaków.
3. Tłumacz kopiuje plik .pot do pliku .po specyficznego dla języka (na przykład de_DE.po) i wypełnia każdy msgstr.
4. Gotowy plik .po jest kompilowany do binarnego pliku .mo.
5. WordPress ładuje plik .mo w czasie działania i wyświetla przetłumaczoną witrynę.

Kiedy programista później dodaje nowe ciągi znaków, plik .pot jest ponownie generowany, nowe wpisy są łączone z każdym istniejącym plikiem .po (zachowując stare tłumaczenia), tłumacz uzupełnia luki, a plik .po jest ponownie kompilowany do .mo. Cykl powtarza się przez cały okres życia projektu.

Kluczowa zasada: edytujesz .po, a następnie kompilujesz do .mo. Nigdy nie edytujesz pliku .mo bezpośrednio i nigdy nie tłumaczysz w pliku .pot. Jeśli chcesz uzyskać pełniejszy obraz od początku do końca, kompleksowy przewodnik po lokalizacji WordPress przedstawia cały potok z przykładami.

Konwencje nazewnictwa i gdzie znajdują się pliki

WordPress jest rygorystyczny w kwestii nazw plików. Pomyl nazewnictwo, a Twój doskonale przetłumaczony plik .mo zostanie po prostu zignorowany, ponieważ WordPress szuka dokładnego dopasowania na podstawie domeny tekstowej i ustawień regionalnych.

Wzorzec nazewnictwa dla tłumaczeń motywów i wtyczek to:

# Pattern: textdomain-locale.po / .mo
twentytwentyfour-de_DE.po      # German (Germany) translation
twentytwentyfour-de_DE.mo      # compiled binary WordPress loads
twentytwentyfour-fr_FR.po      # French (France)
twentytwentyfour.pot           # template, no locale suffix

textdomain pasuje do ciągu znaków przekazanego jako drugi argument do funkcji Gettext, takich jak __( 'Add to Cart', 'twentytwentyfour' ). locale to kod ustawień regionalnych WordPressa, taki jak de_DE, fr_FR lub pt_BR. Szablon .pot nie zawiera sufiksu ustawień regionalnych, ponieważ jest neutralny językowo.

Lokalizacja ma takie samo znaczenie jak nazewnictwo. WordPress przeszukuje kilka przewidywalnych ścieżek:

• Tłumaczenia motywów znajdują się w folderze wp-content/themes/your-theme/languages/ samego motywu.
• Tłumaczenia wtyczek znajdują się w wp-content/plugins/your-plugin/languages/.
• Tłumaczenia z translate.wordpress.org i nadpisania użytkownika trafiają do globalnych katalogów wp-content/languages/themes/ i wp-content/languages/plugins/, które mają priorytet i przetrwają aktualizacje.

Umieść poprawnie nazwany plik de_DE.mo we właściwym folderze, a niemieccy odwiedzający zobaczą język niemiecki. Umieść go o jeden folder za głęboko lub błędnie napisz domenę tekstową, a WordPress cicho powróci do języka angielskiego bez komunikatu o błędzie. Jeśli Twoje tłumaczenia nie pojawiają się, zwykle winowajcą jest niezgodność nazewnictwa lub ścieżki, a przewodnik rozwiązywania problemów z brakującymi tłumaczeniami obejmuje każdą częstą przyczynę.

Dlaczego nigdy nie powinieneś edytować pliku .mo bezpośrednio

Ponieważ plik .mo jest skompilowanym plikiem binarnym, nie ma bezpiecznego sposobu, aby edytować go ręcznie — a wszelkie wprowadzone zmiany zostaną nadpisane przy następnej rekompilacji pliku .po. Plik .po jest źródłem prawdy; plik .mo jest jednorazowym artefaktem kompilacji.

Ta jedna zasada wyjaśnia ogromną część zgłoszeń do pomocy technicznej typu „moje tłumaczenie się zmieniło, ale strona się nie zaktualizowała”. Ktoś zmienia ciąg znaków, zapisuje plik .po i zapomina ponownie skompilować plik .mo. WordPress nadal ładuje stary plik binarny, więc nowe sformułowanie nigdy się nie pojawia. Rozwiązanie jest zawsze takie samo: edytuj .po, ponownie skompiluj do .mo, załaduj ponownie.

Istnieje drugi powód, dla którego ta zasada ma znaczenie: pliki .mo nie są przyjazne dla porównywania (diff) w kontroli wersji. Ponieważ są binarne, niewielka zmiana sformułowania tworzy nieprzejrzystą plamę w historii Git, której żaden recenzent nie może odczytać. Utrzymywanie pliku .po jako śledzonego źródła prawdy i traktowanie pliku .mo jako generowanego artefaktu sprawia, że Twoje repozytorium jest możliwe do przejrzenia, a Twoje tłumaczenia — do audytu.

Robienie tego ręcznie dla dziesiątek języków jest żmudne i podatne na błędy. W tym miejscu przepływ pracy w chmurze oszczędza czas. Narzędzia takie jak SimplePoTranslate tłumaczą Twoje ciągi znaków .po i zwracają pojedynczy plik ZIP zawierający pasujące pliki .po i .mo razem — już skompilowane, poprawnie nazwane, gotowe do umieszczenia w wp-content/languages/. Nie ma nic do ręcznej kompilacji i nie ma ryzyka przestarzałego pliku .mo.

Stosuje również Blokadę Składni, która zamraża wszystkie symbole zastępcze, takie jak %s, %1$s i {name}, a także tagi HTML, przed tłumaczeniem. Twoje zmienne pozostają nienaruszone, więc nigdy nie dostarczasz pliku .mo, który psuje układ. A ponieważ działa w całości w chmurze, nie ma dodatkowej wtyczki obciążającej Twoją stronę — przesyłasz plik i pobierasz gotowe, skompilowane tłumaczenia.

Podsumowanie

Gdy różnica między plikami po vs mo stanie się jasna, cały system tłumaczeń WordPress przestaje wydawać się tajemniczy. Plik .pot to szablon programisty, plik .po to edytowalna kopia robocza tłumacza, a plik .mo to skompilowany plik binarny, który WordPress faktycznie udostępnia odwiedzającym. Tłumaczenia płyną w jednym kierunku — od szablonu do .po do .mo — i zawsze edytujesz ręcznie tylko ten środkowy.

Zapamiętaj trzy zasady, które zapobiegają dziewięćdziesięciu procentom problemów z tłumaczeniem: nigdy nie tłumacz w pliku .pot, zawsze rekompiluj .mo po edycji .po, i dokładnie dopasuj nazewnictwo textdomain-locale. Postępuj zgodnie z nimi, a Twoje przetłumaczone ciągi znaków będą pojawiać się za każdym razem.

Gotowy, aby przestać męczyć się z ręczną kompilacją i nazywaniem plików tłumaczeniowych? Wypróbuj SimplePoTranslate za darmo — karta kredytowa nie jest wymagana. Prześlij swój plik .po lub .pot i otrzymaj gotowy do użycia pakiet .po + .mo w ramach darmowej usługi w ciągu kilku minut.