Lokalizacja

Framework ma wbudowaną obsługę wielojęzycznych aplikacji internetowych. Mechanizm lokalizacji korzysta z rozszerzenia PHP gettext lub, jeśli nie jest ono zainstalowane na serwerze, z podobnej implementacji PHP.

Lokalizacja aplikacji

Aby wyświetlić tłumaczenie ciągu słowo w języku użytkownika, w kodzie należy zastosować następujące konstrukcje:

• w plikach PHP: _w('słowo')
• w szablonach Smarty: [`słowo`]

Jeśli nie zostanie znalezione tłumaczenie ciągu słowo, system wyświetli słowo bez tłumaczenia.

Lokalizacyjne pliki gettext zawierające tłumaczenia łańcuchów interfejsu w różnych językach należy umieścić w strukturze plików aplikacji według następującej zasady: wa-apps/[APP_ID]/locale/[LOCAL]/LC_MESSAGES/[APP_ID].po. Na przykład plik z tłumaczeniem łańcuchów w języku polskim dla aplikacji o identyfikatorze blog powinien znajdować się pod adresem wa-apps/blog/locale/pl_PL/LC_MESSAGES/blog.po.

Plik z rozszerzeniem .po to plik tekstowy w specjalnym formacie, który zawiera tłumaczenia ciągów znaków dla określonego języka lokalnego. Aby włączyć tłumaczenie z pliku .po, należy je skompilować do pliku z rozszerzeniem .mo, na przykład za pomocą programu poEdit.

Przykład zawartości pliku .po z tłumaczeniem łańcuchów na język polski:

msgid ""
msgstr ""
"Project-Id-Version: Guestbook\n"
"POT-Creation-Date: \n"
"PO-Revision-Date: 2022-04-27 10:30+0100\n"
"Last-Translator: \n"
"Language-Team: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : (n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2));\n"
"X-Poedit-Language: pl_PL\n"
"X-Poedit-Country: Polska\n"
"X-Poedit-SourceCharset: utf-8\n"
"X-Poedit-Basepath: .\n"
"X-Poedit-SearchPath-0: .\n"
"X-Poedit-SearchPath-1: .\n"

msgid "Name"
msgstr "Imię"

msgid "Message"
msgstr "Wiadomość"

msgid "post"
msgid_plural "posts"
msgstr[0] "wpis"
msgstr[1] "wpisy"
msgstr[2] "wpisów"

Pary "klucz-tłumaczenie"

Klucz i jego tłumaczenie są reprezentowane w pliku .po przez dwa kolejne wiersze o następującej postaci:

msgid "Name"
msgstr "Imię"

• msgid - jest kluczem łańcucha lokalizacyjnego używanego w kodzie aplikacji (PHP lub Smarty)
• msgstr - tłumaczenie ciągu znaków.

Zaleca się używanie ciągów znaków w języku angielskim jako kluczy lokalizacyjnych. Dzięki temu wniosek jest natychmiast dostępny w języku angielskim. Jeśli brakuje tłumaczeń niektórych lub wszystkich łańcuchów interfejsu, to zamiast tłumaczeń zostaną użyte ich angielskie klucze.

Wielorakie formy ciągów lokalizacyjnych

Wielorakie formy tłumaczenia pozwala na łatwe wyświetlanie słów w wybranej formie w aplikacji, np: 21 wpis, 22 wpisy, 25 wpisów.

Poniższy wiersz w nagłówkach pliku .po informuje, że w języku polskim istnieją trzy formy liczby mnogiej (jak w powyższym przykładzie) i podaje wzór, według którego określa się poprawną formę słowa dla dowolnej liczby całkowitej:

"Plural-Forms: nplurals=3; plural=(n==1 ? 0 : (n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2));\n"

Przykład tłumaczenia formy mnogiej w pliku .po:

msgid "post"
msgid_plural "posts"
msgstr[0] "wpis"
msgstr[1] "wpisy"
msgstr[2] "wpisów"

Aby uzyskać poprawną formę tego słowa w kodzie PHP, użyj następującej konstrukcji:

// zwróci wartość wpis, wpisy lub wpisów w zależności od wartości $n, zgodnie z formułą w pliku .po
_w('post', 'posts', $n);

Podobny szablon dla szablonów Smarty:

{_w('post', 'posts', $n)}

Zwróć uwagę na różnicę między tą konstrukcją a składnią tłumaczenia form regularnych (nie wielorakie) używaną w Smarty. W przypadku tłumaczeń nie liczby mnogiej zaleca się stosowanie w szablonach Smarty konstrukcji typu [`wiersz`].

Funkcja _w() może również automatycznie zastąpić w tłumaczeniu podłańcuch %d przez $n, np. za pomocą funkcji PHP sprintf:

_w('%d file', '%d files', 21); // 21 plik
_w('%d file', '%d files', 22); // 22 pliki
_w('%d file', '%d files', 25); // 25 plików

Automatyczne składanie plików .po

Framework pozwala na automatyczne analizowanie całego kodu aplikacji, zbieranie użytych w nim kluczy lokalizacyjnych i dołączanie brakujących kluczy do pliku .po. Jeśli brakuje samego pliku .po, jest on tworzony automatycznie. Aby uruchomić skrypt do automatycznego budowania pliku .po, wykonaj następujące polecenie w terminalu wiersza poleceń:

• UNIX/Linux/FreeBSD:

  php wa.php locale [app_id]

• Windows:

  php.exe wa.php locale [app_id]

Przykład

php wa.php locale myapp

W ten sam sposób odbywa się automatyczne tworzenie plików .po dla wtyczek, widżetów i motywów projektowych:

php wa.php locale [app_id]/plugins/[plugin_id]
php wa.php locale [app_id]/widgets/[widget_id]
php wa.php locale [app_id]/themes/[theme_id]

Przykłady

php wa.php locale someapp/plugins/myplugin
php wa.php locale someapp/widgets/mywidget
php wa.php locale someapp/themes/mytheme

Generator plików lokalizacyjnych w trybie debugowania

Konstruktor pliku lokalizacyjnego może dodać do pliku .po komentarze zawierające ścieżki do tych plików produktu, w których znaleziono klucze lokalizacyjne.

Przykład

#: /wa-apps/myapp/templates/actions/info.html:38
msgid "Company"
msgstr ""

Ten komentarz wskazuje, że klucz lokalizacyjny został znaleziony przez konstruktora w wierszu 38 podanego pliku. W razie wątpliwości co do najlepszego sposobu przetłumaczenia linii lokalizacyjnej można sprawdzić logikę pliku, w którym jest ona używana.

Aby dodać takie komentarze do pliku .po, należy uruchomić polecenie budowania z parametrem --debug.

Przykład

php wa.php locale myapp --debug

Po przetłumaczeniu wierszy w pliku .po należy ponownie uruchomić program budujący lokalizacje - bez przełącznika --debug. Wywołanie konstruktora bez dodatkowego przełącznika spowoduje usunięcie zbędnych komentarzy z pliku .po i zmniejszenie rozmiaru pliku, który powinien być dołączony do dystrybucji produktu.

Lokalizacja wtyczek aplikacji

Aby zlokalizować wtyczki za pomocą własnych plików lokalizacyjnych, użyj w kodzie PHP funkcji _wp() zamiast _w().

Pliki lokalizacyjne dla wtyczek aplikacji, podobnie jak dla aplikacji, muszą być umieszczone w katalogu locale/[LOCAL]/LC_MESSAGES/ (w podkatalogu wtyczek) i mieć nazwy [app_id]_[plugin_id].po i [app_id]_[plugin_id].mo. Na przykład lokalizacyjny plik .po dla języka polskiego dla wtyczki o identyfikatorze some aplikacji shop powinien znajdować się pod adresem wa-apps/shop/plugins/some/locale/pl_PL/LC_MESSAGES/shop_some.po (plik .mo powinien znajdować się w tym samym katalogu).

Lokalizacja motywów projektowych

Motywy projektu obsługują 2 różne opcje lokalizacji ciągów tekstowych:

• w pliku manifestu theme.xml;
• użycie gettext.

Lokalizacja motywu projektu w manifeście theme.xml.

Ta metoda lokalizacji była tradycyjnie stosowana w motywach projektowych. Aby zlokalizować motyw projektu za pomocą tej metody, dodaj element zagnieżdżony <locales></locales> do głównego elementu XML manifestu, korzystając z poniższego przykładu:

<locales>
    <locale>
        <msgid>String key</msgid>
        <msgstr locale="pl_PL">Tłumaczenie linii</msgstr>
    </locale>
    <locale>
        <msgid>Another string key</msgid>
        <msgstr locale="pl_PL">Przeniesienie innej linii</msgstr>
    </locale>
</locales>

Klucze lokalizacyjne w szablonach motywów projektowych muszą być określone jako

[`String key`]

Lokalizacja motywów projektu za pomocą manifestu nie pozwala na stosowanie wygodnych form liczby mnogiej, dlatego lepiej jest dodać lokalizację za pomocą gettext.

Lokalizacja motywu projektu przy użyciu gettext

Pliki lokalizacyjne dla motywu projektu wykorzystującego gettext powinny znajdować się w katalogach podobnych do wa-apps/[app_id]/themes/[theme_id]/locale/[locale_id]/LC_MESSAGES/[app_id]_[theme_id].po. Aby szybko utworzyć pliki lokalizacyjne, wygodnie jest użyć polecenia automatycznego budowania.

W przypadku korzystania z tej metody należy w taki sam sposób określić w szablonach pojedyncze klucze lokalizacyjne:

[`String key`]

A formy liczby mnogiej w szablonach projektów należy dodać w formacie

{_wp('%d product', '%d products', $n)}

Lokalizacja wtyczek systemowych

W nazwach plików lokalizacyjnych wtyczek systemowych znajdujących się w katalogu wa-plugins/ jako przedrostka nazwy należy użyć identyfikatorów payment_, shipping_, sms_, w zależności od nazwy podkatalogu, w którym znajduje się wtyczka systemowa. Przykład pliku .po z lokalizacją dla języka polskiego dla wtyczki płatności o identyfikatorze some: wa-plugins/payment/some/locale/pl_PL/LC_MESSAGES/payment_some.po

Aby umieścić łańcuchy lokalizacyjne wtyczki systemowej w jej kodzie źródłowym, należy użyć metody publicznej _w() klasy bazowej waSystemPlugin, jak pokazano poniżej:

• W kodzie PHP

  $this->_w('name')

• W szablonach HTML

  {$p->_w('name')}

Opracowywanie produktu przeznaczonego do użytku tylko w jednym języku

Jeśli produkt (aplikacja lub wtyczka) jest przeznaczony do użytku tylko w jednym języku, nie trzeba korzystać z mechanizmu lokalizacji. W takim przypadku należy zapisać wszystkie ciągi lokalizacyjne w kodzie źródłowym produktu bezpośrednio w języku, w którym będzie on używany. Konstrukcje _w(), _wp() i [``] nie muszą być w tym przypadku używane.