Utwórz niestandardowy blok Gutenberga – Część 8: Obsługa tłumaczeń

W tej części skupimy się na tłumaczeniu tekstów i wartości w naszym niestandardowym bloku Gutenberga. Używamy WP-CLI do generowania niezbędnych plików, aby Gutenberg mógł załadować nasze tłumaczenia przy zmianie języka WordPress.

Zanim to zrobisz, musisz mieć zainstalowany WP CLI (interfejs wiersza poleceń dla WordPress). Jeśli go nie masz, po prostu postępuj zgodnie z przewodnikiem w Podręczniku WordPress dla CLI.

Krótko mówiąc, jak tłumaczyć skrypty JavaScript (Gutenberg): WordPress wymaga .moplików do tłumaczenia plików PHP, ale dla JavaScript WordPress wymaga .jsonpliku. Każdy plik JavaScript wymaga jednego pliku JSON do tłumaczenia. JSON powinien mieć określony format (WP CLI wygeneruje go dla nas) z naszymi przetłumaczonymi ciągami. Potrzebujemy jednego pliku JSON na język, na który chcemy tłumaczyć.

Musimy więc najpierw dodać funkcje gettext (__(), _e()itp.) do naszych plików JavaScript i jak zwykle wygenerować plik PO dla naszego motywu lub wtyczki. Ponieważ opakowaliśmy teksty w naszych plikach skryptowych np __()., plik PO powinien być w stanie je zawierać. Następnie wykonujemy tłumaczenie jak zwykle w naszym pliku PO. A potem w końcu używamy WP CLI, aby wyodrębnić niezbędne ciągi z pliku PO i wygenerować pliki JSON dla wszystkich naszych plików JavaScript.

Pamiętaj, że Twój motyw lub pliki .po/ .mo-wtyczki nigdy nie będą miały wpływu na Twoje pliki JavaScript – nawet jeśli zawierają one przetłumaczone ciągi z naszych plików JavaScript.

Implementacja tłumaczenia w JavaScript

Pierwszym krokiem jest umieszczenie wszystkich tekstów w naszym pliku JavaScript wewnątrz funkcji tłumaczenia. Jeśli zajmowałeś się tłumaczeniem WordPressa w PHP, prawdopodobnie dobrze znasz funkcje __(), _e()i esc_html__()tak dalej. WordPress posiada pakiet wp.i18nzawierający te funkcje, które działają dokładnie tak, jak w PHP.

Podobnie jak w przypadku PHP, musisz podać domenę textdomain (nazwa/uchwyt). Może to być cokolwiek chcesz, ale trzymaj się krótkich, ponieważ prawdopodobnie będziesz musiał je wpisywać bardzo często. Dla mojego motywu ustawiłem moją textdomain z domeną awhitepixel. Więc w PHP zrobię __('My string', 'awhitepixel')tłumaczenie łańcuchów i będzie to dokładnie to samo w plikach JavaScript.

Zacznijmy edytować nasz plik JavaScript. Najpierw musimy zdestrukturyzować funkcję __i _ez wp.i18npakietu. Ze względu na charakter React najprawdopodobniej będziesz w większości, a może tylko korzystać z tej __funkcji.

const { __, _e } = wp.i18n;

A potem jest kwestia znalezienia wszystkich naszych zakodowanych na sztywno tekstów w pliku JavaScript i ich aktualizacji. Pamiętaj, że funkcje __i _ewymagają kontekstu JavaScript. Oznacza to, że gdy wpisujemy stringi jako na przykład wartości właściwości obiektu, używamy __()od razu, ale jako wartości np. rekwizytów musimy wszystko zawinąć do środka { }, aby zaznaczyć, że jest to kod JavaScript.

Na przykład nasza registerBlockTypeobsługa tłumaczenia będzie wyglądać tak:

registerBlockType('awp/firstblock', {
    title: __('My first block', 'awhitepixel'), 
    category: 'common',
    icon: 'smiley',
    description: __('Learning in progress', 'awhitepixel'),
    keywords: [__('example', 'awhitepixel'), __('test', 'awhitepixel')],
    attributes: {
        ...

A co do rekwizytów, czyli w InspectorControls:

Zawiń wszystkie teksty, dla których chcesz obsługiwać tłumaczenie w __()i _e(). Jeśli wykonałeś ten samouczek krok po kroku, nie powinieneś mieć żadnych przypadków, w których musisz użyć _e(). Kiedy skończysz, ponownie skompiluj JavaScript, a my odejdziemy od JavaScript.

Konfigurowanie plików po i/lub pot

Ten krok różni się nieco w zależności od tego, co już zrobiłeś i skonfigurowałeś dla swojego motywu lub wtyczki. Być może piszesz skrypty Gutenberga w nowej i pustej wtyczce, która nie została skonfigurowana do tłumaczenia PHP, lub w motywie, który ma już zarejestrowaną domenę tekstową. Możesz mieć gotowe pliki PO (i MO) lub możesz mieć tylko plik POT. Postaram się jak najlepiej objąć wszystkie podstawy.

Mój motyw lub wtyczka ma już plik po(t)

Jeśli masz już plik PO lub POT w swoim projekcie, najprawdopodobniej masz również funkcję PHP load_theme_textdomain()lub gdzieś w swoim kodzie. Upewnij się, że zarejestrowana domena jest taka sama, jak w plikach JavaScript.load_child_theme_textdomain()``load_plugin_textdomain()

Wszystko, co musisz zrobić, to załadować plik PO dla języka, który chcesz przetłumaczyć (lub wygenerować plik z pliku POT) na przykład w PoEdit. Kliknij „Aktualizuj z kodu" (lub podobnie w innych programach), aby program mógł przeskanować wszystkie pliki projektu (w tym nasze ostatnio zaktualizowane pliki JavaScript) i zaktualizować pulę ciągów do tłumaczenia. Ciągi w naszym pliku JavaScript powinny się pojawić. Następnie wystarczy przetłumaczyć je jak zwykle i zapisać.

PS: Jeśli nie możesz kliknąć „Aktualizuj z kodu” lub ponownie przeskanować pliki, prawdopodobnie plik PO nie został poprawnie skonfigurowany. Poszukaj wskazówek w następnej sekcji.

Nie mam żadnych plików tłumaczeniowych

Jeśli Twój motyw lub projekt nie został skonfigurowany z tłumaczeniem, musisz wygenerować plik POT za pomocą WP-CLI lub ręcznie utworzyć plik PO.

Mam dokładny przewodnik, jak utworzyć plik PO w moim samouczku motywu dla początkujących – część 8. W poście opisano, jak utworzyć plik i poprawnie go skonfigurować, aby przeszukiwać pliki motywów, oraz słowa kluczowe do wyszukania (__, _e, itp.).

Jeśli wolisz utworzyć plik POT, możesz użyć polecenia wp i18n make-pot w WP-CLI, a następnie utworzyć z tego plik PO za pomocą np. PoEdit. Pamiętaj, że będziesz musiał ponownie wygenerować plik POT (a następnie plik PO) za każdym razem, gdy aktualizujesz dowolne ciągi w kodzie.

Wynik końcowy

Tym, czego ostatecznie potrzebujesz, jest plik PO, który znalazł ciągi JavaScript w miejscu, w którym zostały one przetłumaczone. Zalecam umieszczenie plików tłumaczeń w osobnym folderze w motywie lub wtyczce. Kiedy zaczniemy generować pliki JSON, otrzymamy całkiem sporo plików do tłumaczenia i fajnie będzie trzymać je wszystkie razem we własnym folderze.

Jako punkt odniesienia umieszczam wszystkie pliki tłumaczeń w moim theme/assets/lang/. Dodałem norweskie tłumaczenie dla mojego motywu o nazwie nb_NO.po, które zawiera przetłumaczone ciągi z naszego niestandardowego pliku JavaScript bloku.

Generowanie plików JSON z pliku po

Następnym krokiem jest użycie WP-CLI do wygenerowania plików JSON z naszego pliku po. W tym celu używamy polecenia wp i18n make-json.

Należy pamiętać, że domyślnie to polecenie usunie przetłumaczone ciągi z pliku PO do użycia podczas generowania pliku JSON. Może to być uciążliwe w trakcie opracowywania motywu lub wtyczki. Ponieważ kiedy dodasz nowe lub dostosujesz ciągi, będziesz musiał ponownie przeskanować pliki i ponownie przetłumaczyć wszystkie ciągi (i znowu i znowu). Na szczęście w poleceniu jest flaga, aby tego uniknąć.

Zaczynajmy! W swoim terminalu przejdź do katalogu językowego dla swojego projektu. Uruchom następujące polecenie i odnieś się do swojego pliku po (jak wspomniano, mam nb_NO.pogotowy plik).

wp i18n make-json nb_NO.po --no-purge

Jeśli nie masz problemu z usunięciem przetłumaczonych napisów z pliku PO (na przykład, jeśli tworzysz ostateczną wersję), możesz pominąć --no-purgeflagę.

Terminal powinien wyświetlić komunikat „Sukces” i podać liczbę utworzonych plików JSON. Jeśli widzisz, że wygenerował dwa pliki JSON, dzieje się tak dlatego, że odczytał zarówno nasz kod źródłowy pliku JavaScript, jak i plik kompilacji, i wygenerował po jednym dla każdego. Jeśli masz więcej plików JavaScript w swoim projekcie, otrzymasz jeszcze więcej plików JSON.

W momencie pisania tego (WordPress v 5.3.2 i WP-CLI wersja 2.4.0) pliki JSON są generowane z kodem języka i hashem – zagadkowym ciągiem jako nazwami plików. Musimy znaleźć właściwy i zmienić jego nazwę.

Zmiana nazwy pliku JSON i ładowanie go w PHP

Twój folder językowy prawdopodobnie wygląda mniej więcej tak:

Pamiętaj, że polecenie wygenerowało jeden plik JSON na plik JavaScript – a ponieważ w rzeczywistości mamy dwa pliki dla naszego niestandardowego bloku (źródło i kompilacja), wygenerowało dwa pliki. Jeśli Twój kod JavaScript jest podzielony na kilka plików, każdy otrzyma dwa własne pliki JSON.

Jeśli siedzisz z tylko dwoma plikami JSON (ponieważ nie znaleziono innych plików JavaScript), możesz teraz usunąć jeden z nich. Jeśli masz więcej niż dwa, musisz otworzyć pliki JSON i zobaczyć, do jakiego pliku są przeznaczone. Pliki JSON zawierają właściwość „ source“, która informuje, do którego pliku JavaScript jest przeznaczony ten plik JSON. Użyj tego, aby dowiedzieć się, który plik JSON zachować. Zalecam znalezienie ostatecznego pliku kompilacji (w przeciwieństwie do plików deweloperskich), ponieważ powinien on zawierać wszystkie ciągi ze wszystkich plików.

Kiedy znajdziesz właściwy, musimy zmienić jego nazwę. Musimy zmienić jego nazwę, aby podążała za tym wzorem:

[textdomain]-[language code]-[script handle].json

Użyj domeny tekstowej, której używałeś wszędzie (np __('My string', 'awhitepixel'). ), dodaj myślnik i kod języka. Następnie podaj myślnik i uchwyt skryptu użyty do zarejestrowania pliku JavaScript Gutenberga (wp_register_script()). Jako odniesienie, moja domena tekstowa to awhitepixel, mój kod języka to nb_NO, a mój uchwyt skryptu dla skryptu Gutenberga to awp-myfirstblock-js. Zmieniam więc nazwę pliku JSON na:

awhitepixel-nb_NO-awp-myfirstblock-js.json

Powiedz WordPressowi, aby wczytał nasz JSON

Teraz pozostaje tylko ostatni krok – nakazanie WordPressowi załadowania naszego pliku JSON. Musimy użyć funkcji [wp_set_script_translations](https://developer.wordpress.org/reference/functions/wp_set_script_translations/)(). Jest to całkiem nowa funkcja WordPressa, więc polecam zawinąć ją w function_exists(). Akceptuje trzy parametry; uchwyt skryptu dla naszego bloku, textdomain i ścieżka do naszego folderu tłumaczenia (uwaga: ścieżka, a nie adres URL).

Wewnątrz naszej funkcji podpiętej do init, gdzie zarejestrowaliśmy nasz skrypt blokowy i wywołanie register_block_type, możemy również wywołać tę nową funkcję, aby załadować nasz plik tłumaczenia JSON. PS: Pamiętaj, że hook enqueue_block_assetsnie będzie działał przy rejestracji tłumaczeń.

add_action('init', function() {
    wp_register_script('awp-myfirstblock-js', ....);
    register_block_type('awp/firstblock', ....
 
    if (function_exists('wp_set_script_translations')) {
        wp_set_script_translations('awp-myfirstblock-js', 'awhitepixel', get_template_directory(). '/assets/lang');
    }
});

I to wszystko! Twój blok powinien zostać teraz przetłumaczony. Zmień język WordPressa na język, na który przetłumaczyłeś i sprawdź sam. Kiedy zmieniam język WordPressa na norweski i dodaję swój blok, nazwa i wszystko w nim jest tłumaczone: