Umiędzynaradawianie

Umiędzynaradawianie (I18N) odnosi się do procesu projektowania oprogramowania, tak aby mogło ono być dostosowane do różnych języków oraz regionów bez potrzeby zmian w mechanice aplikacji. Dla aplikacji sieciowych ma to szczególne znaczenie ponieważ użytkownicy mogą pochodzić z całego świata.

Yii dostarcza wsparcia dla I18N w kilku aspektach.

• Dostarcza lokalne dane dla każdego możliwego języka oraz wariantu.
• Zawiera usługę tłumaczenia wiadomość oraz plików.
• Zapewnia zależne od ustawień lokalnych formatowanie daty i czasu.
• Zapewnia zależne od ustawień lokalnych formatowanie liczb.

In the following subsections, we will elaborate each of the above aspects.

1. Ustawienia lokalne i języki. ¶

Ustawienia lokalne są zestawem parametrów, które określają język użytkownika, jego kraj oraz specjalny wariant preferencji, które użytkownik chce zobaczyć
w interfejsie użytkownika. Najczęściej identyfikacja odbywa się poprzez ID zawierające ID języka oraz ID regionu. Na przykład, ID en_US oznacza angielskie ustawienia lokalne
dla USA. Aby zachować spójność wszystkie ID ustawień lokalnych w Yii zostały sprowadzone do postaci kanonicznych w formacie LanguageID lub LanguageID_RegionID zapisanych małymi literami (np. en, en_us).

Dane lokalne są reprezentowane jako instancja CLocale. Dostarcza ona zależne od ustawień lokalnych informacje, w tym symbole waluty, symbole liczb, formaty walut, formaty liczb, formaty daty i czasu oraz nazwy dni i miesięcy. Ponieważ informacja o języku znajduje się
już w ID ustawień lokalnych nie jest ona dostarczona przez CLocale. Z tego samego
powodu często zamiennie używamy terminów ustawienia lokalne i język.

Mając ID ustawień lokalnych można otrzymać odpowiadającą mu instancję CLocale poprzez CLocale::getInstance($localeID) lub CApplication::getLocale($localeID).

Info: Yii dostarcza dane lokalne dla prawie każdego języka oraz regionu. Dane uzyskano z Wspólnego repozytorium danych lokalnych (CLDR). Dla każdego ustawienia lokalnego wyłącznie zbiór danych pochodzących z CLDR jest dostarczany, gdyż w oryginalnych danych dostępnych jest wiele rzadko używanych informacji.

Dla aplikacji Yii rozróżniamy jej język docelowy od języka źródłowego. Język docelowy jest językiem (lokalnego) użytkownika do którego skierowana jest aplikacja, zaś język źródłowy odnosi się do języka (lokalnego) w którym pliki źródłowe aplikacji zostały napisane. Umiędzynaradawianie występuje tylko wtedy, gdy te dwa języki są różne. different.

Można skonfigurować język docelowy w konfiguracji aplikacji lub zmienić go dynamicznie zanim jakiekolwiek umiędzynaradawianie będzie miało miejsce., or

Wskazówka: Czasami, możemy chcieć ustawić język docelowy jako język preferowany przez użytkownika (zdefiniowany w ustawieniach przeglądarki użytkownika). Aby tak zrobić, możemy pobrać preferowane przez użytkownika ID języka używając CHttpRequest::preferredLanguage.

2. Tłumaczenie ¶

Najbardziej pożądaną funkcjonalnością I18N jest tłumaczenie, włączając w to tłumaczenie komunikatów raz tłumaczenie widoków. Pierwsze tłumaczy treść komunikatu na pożądany język, drugie zaś tłumaczy cały plik na pożądany język. Żądanie tłumaczenia zawiera obiekt, który ma zostać przetłumaczony, język źródłowy obiektu oraz język docelowy na który obiekt powinien zostać przetłumaczony. W Yii domyślnie językiem źródłowym
język źródłowy aplikacji zaś językiem docelowym jest domyślnie język aplikacji. Jeśli język źródłowy oraz docelowy są takie same, translacja nie zachodzi.

Tłumaczenie komunikatów

Tłumaczenie komunikatów odbywa się poprzez wywołanie metody Yii::t(). Metoda ta tłumaczy podaną wiadomość w języku źródłowym na język docelowy.

Podczas tłumaczenia komunikatu jego kategoria powinna zostać określona, ponieważ komunikat może zostać różnie przetłumaczony w różnych kategoriach (kontekstach). Kategoria yii jest zarezerwowana dla komunikatów używanych przez kod kod źródłowy frameworku.

Komunikaty mogą posiadać symbol zastępczy (placeholder), który będzie zastąpiony przez aktulną wartość parametru podczas wywoływania metody Yii::t()|YiiBase::t]. Na przykład następujące żądanie tłumaczenia komunikatu zastąpi symbol zastępczy {alias} w oryginalnym komunikacie aktualną wartością zmiennej alias.

Yii::t('yii', 'Path alias "{alias}" is redefined.',
    array('{alias}'=>$alias))

Uwaga: Aby móc przetłumaczyć komunikat musi on być stałym łańcuchem znaków. Nie powinien on zawierać zmiennych, które mogą zmienić zawartość wiadomości (no. "Invalid {$message} content."). Używaj symbolów zastępczych jeśli komunikat musi się zmieniać w zależności od parametrów.

Przetłumaczone komunikaty znajdują się w repozytorium nazwanym źródłem komunikatów. Źródło komunikatów reprezentowane jest poprzez instancję klasy CMessageSource lub jej klas pochodnych. Podczas wywołania Yii::t(), szuka ona komunikatu w źródle komunikatów i zwraca jego przetłumaczoną wersję jeśli taką znajdzie.

Yii dostarcza następujących typów źródeł komunikatów. Możesz również rozszerzyć klasę CMessageSource aby utworzyć swoje własne źródło komunikatów.

• CPhpMessageSource: tłumaczenia komunikatów przechowywane są jako pary klucz-wartość w tablicy PHP. Oryginalny komunikat jest kluczem a przetłumaczony wartością. Każda tablica reprezentuje tłumaczenie dla konkretnej kategorii komunikatów i przechowywana jest w oddzielnym pliku skryptu PHP, którego nazwa jest nazwą kategorii. Pliki z tłumaczeniami PHP dla tych samych języków przechowywane są w tym
  samym folderze o nazwie takiej jak lokalne ID. Te wszystkie katalogi znajdują się w katalogu określonym przez zmienną bazePath.

• CGettextMessageSource: tłumaczenia komunikatów przechowywane są jako GNU Gettext files.

• CDbMessageSource: tłumaczenia komunikatów przechowywane są w tabeli bazy danych. Aby uzyskać więcej szczegółów spójrz w dokumentację API dla CDbMessageSource.

Źródło komunikatów jest ładowane jako komponent aplikacji. Yii predefiniuje komponent o nazwie messages w celu przechowywania komunikatów, które będą używane w aplikacji. Domyślnym typem źródła komunikatów jest CPhpMessageSource zaś ścieżką bazowa gdzie przechowywane są pliki z tłumaczeniami jest protected/messages.

Podsumowując, w celu korzystania z tłumaczenia komunikatów, nastepujące kroki są wymagane:

1. Wywołaj Yii::t() w odpowiednim miejscu;

2. Utwórz plik tłumaczenia PHP jako protected/messages/LokalneID/NazwaKategorii.php. Każdy plik po prostu zwraca tablicę tłumaczeń komunikatów. Zauważ, oznacza to, że założyliśmy iż używasz domyślnej klasy CPhpMessageSource w celu przechowywania przetłumaczonych komunikatów.

3. Skonfiguruj właściwości CApplication::sourceLanguage oraz CApplication::language.

Wskazówka: Narzędzie yiic może zostać użyte do zarządzania tłumaczeniami komunikatów jeśli używamy CPhpMessageSource jako źródło komunikatów. Jego polecenie message
może automatycznie wydobyć komunikaty, które powinny zostać przetłumaczone z wybranego pliku źródłowego oraz połączyć je do istniejącymi tłumaczeniami, jeśli jest to konieczne.

Od wersji 1.0.2, Yii posiada dodane wsparcie dla alternatywnych formatów. Alternatywny format odnosi się do wybierania tłumaczenia w zależności od podanej wartości numerycznej. Na przykład w języku angielskim słowo 'book' oznaczające książkę może przyjmować formę liczby pojedynczej lub też formę liczby mnogiej, w zależności od ilości książek, gdy zaś w innych językach, słowo to może nie posiadać różnych form (tak jak w języku chińskim) albo też może mieć dużo bardziej skomplikowaną liczbę mnogą (tak jak w rosyjskim). Format alternatywny rozwiązuje ten problem w najprostszy ale skuteczny sposób. Aby móc używać formatu alternatywnego, przetłumaczony komunikat musi podsiadać sekwencję par wyrażenie-komunikat rozdzielonych znakiem |, tak jak pokazano poniżej:

'expr1#message1|expr2#message2|expr3#message3'

gdzie exprN odnosi się do poprawnego wyrażenia PHP, którego wynik ma postać boolean, która determinuje czy odpowiedni komunikat powinien zostać zwrócony. Wyłącznie
komunikat odpowiadający pierwszemu wyrażeniu, którego ewaluacji zakończyła się wynikiem true, zostanie zwrócony. Wyrażenie może zawierać specjalną zmienną o nazwie n (zauważ, że to nie $n), która przejmie wartość liczby przekazaną jako pierwszy parametr komunikatu. Na przykład, zakładając, ze tłumaczona wiadomość to:

'n==1#one book|n>1#many books'

i że przekazujemy wartość liczbową 2 w w tablicy parametrów komunikatu podczas wywoływania metody Yii::t(), otrzymamy many books jako końcowy wynik tłumaczenia komunikatu.

W skróconej notacji, jeśli wyrażenie jest liczbą, będzie ono potraktowane jako n==Liczba. Dlatego, powyższej tłumaczony komunikat, może również być zapisany jako:

'1#one book|n>1#many books'

Tłumaczenie pliku

Tłumaczenie plików dokonuje się poprzez wywołanie metody CApplication::findLocalizedFile(). Podając ścieżkę do pliku, który ma zostać przetłumaczony, metoda będzie szukała pliku o tej samej nazwie w podkatalogu LokalneId. Jeśli znajdzie plik, ścieżka do plik zostanie zwrócona; w przeciwnym przypadku, oryginalna ścieżka do pliku zostanie zwrócona.

Tłumaczenie plików jest głównie używane podczas generowania widoku. Podczas wywoływania jednej z metod generowania w kontrolerze albo w widżecie, plik widoku będzie przetłumaczony automatycznie. Na przykład, jeśli językiem docelowym jest zh_cn a językiem źródłowym jest en_us, generowanie widoku o nazwie edit zakończy się poszukiwaniem następującego pliku widoku protected/views/ControllerID/zh_cn/edit.php. Jeśli plik zostanie znaleziony, ta przetłumaczona wersja będzie używana do generowania; w przeciwnym przypadku plik protected/views/ControllerID/edit.php będzie używany do renderowania w zamian.

Tłumaczenie plików może również być używane dla innych celów na przykład, do wyświetlania przetłumaczonych obrazków czy też zależnych od ustawień lokalnych plików danych.

3. Formatowanie daty i czasu ¶

Data i czas są posiadają często różne formaty w poszczególnych państwach czy też regionach. Dlatego też zadanie formatowania daty i czasu polega na generowaniu ciągu reprezentującego ate lub czas, który zgadza się z tym określonym przez ustawienia lokalne. Yii dostarcza w tym celu klasę CDateFormatter.

Każda instancja CDateFormatter jest powiązana z docelowymi ustawieniami lokalnymi. Aby uzyskać klasę formatującą powiązaną z docelowymi ustawieniami lokalnymi aplikacji możemy po prostu skorzystać z właściwości aplikacji dateFormatter.

Klasa CDateFormatter dostarcza przede wszystkim dwóch metod do formatowania znacznika czasu (ang. timestamp) UNIX.

• format: metoda ta formatuje podany znacznik czasowy UNIX do łańcucha odpowiadającego spersonalizowanemu wzorcowi (np.$dateFormatter->format('yyyy-MM-dd',$timestamp)).

• formatDateTime: metoda ta formatuje dany znacznik czasu UNIX do łańcucha odpowiadającemu wzorcowi predefiniowanemu w danych docelowych ustawień lokalnych
  (np. short krótki format daty, long długi format czasu).

4. Formatowanie liczb ¶

Tak jak data i czas, liczby również mogą być formatowanie różnie w zależności od kraju czy też regionu. Formatowanie licz obejmuje formatowanie dziesiętne, formatowanie walut
oraz formatowanie procentów. Dla tych zadań, Yii dostarcza klasy CNumberFormatter.

Aby uzyskać klasę formatowania powiązaną z docelowymi ustawieniami lokalnymi aplikacji, możemy skorzystać z właściwości numberFormatter danej aplikacji.

Następujące metody są dostarczane przez klasę CNumberFormatter aby sformatować wartość całkowitą lub zmiennoprzeciwkową.

• format: metoda ta formatuje podany numer do łańcucha uwzględniając spersonalizowany wzorzec (np. $numberFormatter->format('#,##0.00',$number)).

• formatDecimal: metoda ta formatuje podany numer przy użyciu wzorca dziesiętnego z danych docelowych ustawień lokalnych.

• formatCurrency: metoda ta formatuje podaną liczbę oraz kod waluty używając wzorca walutowego predefiniowanego w danych docelowych, lokalnych ustawień.

• formatPercentage: metoda ta formatuje podaną liczbę używając wzorca procentowego predefiniowanego w danych źródłowych lokalnych ustawień.