# Użycie Zend_Locale

`Zend_Locale` udostępnia zlokalizowane informacje o innych locale. Włączając w to nazwy innych locale, dni tygodnia, miesięcy itp.

## Kopiowanie, klonowanie oraz serializowanie obiektów locale

Aby pomyślnie zduplikować obiekt locale należy użyć klonowania obiektów. Większość metod świadomych locale przyjmują w argumencie nazwę locale, taką jaka jest zwracana przez `$locale->toString()`.

### Klonowanie

    $locale = new Zend_Locale('ar');

    // Serializacja oraz zapisanie obiektu $locale
    $serializedLocale = $locale->serialize();
    // odtworzenie oryginalnego obiektu
    $localeObject = unserialize($serializedLocale);

    // Uzyskanie identyfikatora locale
    $stringLocale = $locale->toString();

    // Utworzenie kopii obiektu $locale
    $copiedLocale = clone $locale;

    print "copied: ", $copiedLocale->toString();

    // PHP automatycznie wywołuje toString() poprzez __toString()
    print "copied: ", $copiedLocale;

## Równość

`Zend_Locale` udostępnia wygodną funkcję służącą do porównania dwóch locale. Wszystkie klasy świadome locale powinny umożliwiać podobną funkcjonalność.

### Sprawdzenie równoważnych locale

    $locale = new Zend_Locale();
    $mylocale = new Zend_Locale('en_US');

    // Sprawdzenie równoważności
    if ($locale->equals($mylocale)) {
        print "Locales are equal";
    }

## Domyślne locale

Metoda `getDefault()` zwraca tablicę identyfikatorów locale na podstawie informacji udostępnianych przez przeglądarkę użytkownika (jeśli jest dostępna), informacji pochodzących ze środowiska serwera hostingowego lub z ustawień Zend Framework. Pierwszy parametr określa preferencję źródła ((`BROWSER`, `ENVIRONMENT`, or `FRAMEWORK`). Drugi parametr określa czy mają być zwrócone wszystkie locale wyszczególnione w źródle czy tylko pierwsze z nich. Komponenty świadome locale używają przeważnie jedynie pierwszego locale, w zależności od oceny ich preferencji (jeśli jest dostępna).

### Zwrócenie domyślnego locale

    $locale = new Zend_Locale();

    // Zwrócenie wszystkich domyślnych locale
    $found = $locale->getDefault();
    print_r($found);

    // Zwrócenie jedynie locale domyślnego dla przeglądarki
    $found2 = $locale->getDefault(Zend_Locale::BROWSER,TRUE);
    print_r($found2);

Aby uzyskać locale domyślne dla określonego źródła: `BROWSER`, `ENVIRONMENT` lub `FRAMEWORK`, należy skorzystać z odpowiedniej metody:

- `getEnvironment()`

- `getBrowser()`

## Ustawienie nowego locale

Nowe locale może zostać ustawione za pomocą metody `setLocale()`. Przyjmuje ona łańcuch znaków identyfikatora locale jako parametr. Jeśli argument nie zostanie podany to nastąpi próba automatycznego wyboru. Ponieważ obiekty `Zend_Locale` są "lekkie" metoda ta istnieje głównie po to aby wykluczyć efekty uboczne w kodzie, który odnosi się do już istniejącej instancji.

### Metoda setLocale()

    $locale = new Zend_Locale();

    // Obecne locale
    print $locale->toString();

    // Nowe locale
    $locale->setLocale('aa_DJ');
    print $locale->toString();

## Zwrócenie języka i regionu

Aby uzyskać skrót języka z identyfikatora locale należy skorzystać z metody `getLanguage()`. Do uzyskania skrótu regionu służy metoda `getRegion()`.

### getLanguage oraz getRegion

    $locale = new Zend_Locale();

    // jeśli locale to 'de_AT' wtedy 'de' zostanie zwrócone jako język
    print $locale->getLanguage();

    // jeśli locale to 'de_AT' wtedy 'AT' zostanie zwrócone region
    print $locale->getRegion();

## Uzyskanie zlokalizowanych łańcuchów znaków

Metoda `getTranslationList()` umożliwia dostęp do zlokalizowanych danych różnego rodzaju. Te informacje są przydatne jeśli zajdzie potrzeba zaprezentowania użytkownikowi zlokalizowanych danych. W takiej sytuacji nie ma potrzeby własnoręcznego tłumaczenia - odpowiednie dane są dostępne do użytku.

Lista żądanych danych jest zawsze zwracana w postaci tablic asocjacyjnych. Jeśli istnieje potrzeba przekazania więcej niż jednego parametru do określonego typu, z którego chce się pobrać wartości to należy przekazać te parametry w postaci tablicy.

### getTranslationList

    $list = Zend_Locale::getTranslationList('language', 'de_AT');

    print_r ($list);
    // przykładowe pary klucz -> wartość
    // [de] -> Deutsch
    // [en] -> Englisch

    // użycie jednego ze zwróconych kluczy jako parametru metody getTranslation()
    // dla innego języka
    print Zend_Locale::getTranslation('de', 'language', 'zh');
    // zwraca tłumaczenie nazwy języka określonego jako 'de' w języku chińskim

Podobne informacje można uzyskać dla wszystkich języków ale w niektórych przypadkach nie wszystkie dane są dostępne. Aby ułatwić dostęp do nich, pewne typy informacji są również dostępne poprzez dedykowane metody. Niżej znajduje się obszerniejszy opis.

### Szczegóły użycia metody getTranslationList($type = null, $locale = null, $value = null)

Typ | Opis
--- | ---
Language | Zwraca zlokalizowaną listę wszystkich języków. Część identyfikatora locale wskazująca na język jest zwracana w kluczu a pełna nazwa w wartości
Script | Zwraca zlokalizowaną listę systemów pisma. Identyfikator systemu zwracany jest w kluczu, przetłumaczona nazwa - w wartości

Territory

Zwraca zlokalizowaną listę wszystkich terytoriów. Zawiera kraje, kontynenty i inne terytoria. Aby uzyskać jedynie terytoria i kontynenty należy przekazać jako wartość 1. Aby uzyskać kraje - 2. Tam gdzie jest to możliwe część locale wskazująca na kraj jest zwracana w kluczu, w pozostałych przypadkach podany jest oficjalny kod ISO danego terytorium. Przetłumaczona nazwa terytorium zwracana jest w wartości

Variant | Zwraca zlokalizowaną listę odmian systemów pisma. Identyfikator odmiany w kluczu a przetłumaczona nazwa w wartości
Key | Zwraca zlokalizowaną listę znanych kluczy. Są to generyczne wartości używane w tłumaczeniu. Są to kalendarz, sortowanie i waluta. W kluczu zwracany jest klucz a przetłumaczona nazwa w wartości
Type | Zwraca zlokalizowaną listę typów kluczy. Są to rodzaje kalendarzy oraz porządków sortowania. Jeśli poda się parametr 'collation' to zostanie zwrócona lista porządków sortowania. Dla parametru 'calendar' - rodzajów kalendarzy. Jeśli parametr nie zostanie podany to lista zwrotna będzie zawierała oba rodzaje danych. Rodzaj jest podany w kluczu a przetłumaczona nazwa w wartości
Layout | Zwraca listę zasad formatowania specjalnych znaków tekstowych
Characters | Zwraca listę dozwolonych znaków w ramach danego locale
Delimiters | Zwraca listę dozwolonych znaków służących do umieszczania w cudzysłowu dla danego locale
Measurement | Zwraca listę znanych jednostek miary. Lista jest nieaktualna
Months | Zwraca listę nazw miesięcy w danym locale. Zwracanych jest kilka różnych form reprezentacji miesięcy - każda w oddzielnej tablicy zagnieżdżonej. Jeśli nie poda się parametru to zostanie zwrócona pełna lista miesięcy z kalendarza gregoriańskiego. Można podać inną, znaną nazwę kalendarza aby uzyskać jego nazwy miesięcy. Z uwagi na prostotę można zamiast tego używać Zend_Date

Month

Zwraca zlokalizowaną listę miesięcy. Bez podania parametru zwracana jest zwykła lista pełnych nazw miesięcy wg. kalendarza gregoriańskiego. Numer porządkowy miesiąca znajduje się w kluczu a przetłumaczona nazwa w wartości. Można uzyskać nazwy miesięcy z innego kalendarza jeśli poda się tablicę w parametrze. Pierwszą wartością tej tablicy powinna być nazwa kalendarza, drugą - kontekst, trzecią - szerokość zwracanych danych. Z uwagi na prostotę można zamiast tego używać Zend_Date

Days | Zwraca listę nazw dni tygodnia w danym locale. Zwracanych jest kilka różnych form reprezentacji dni - każda w oddzielnej tablicy zagnieżdżonej. Jeśli nie poda się parametru to zostanie zwrócona pełna lista dni tygodnia z kalendarza gregoriańskiego. Można podać inną, znaną nazwę kalendarza aby uzyskać jego nazwy dni tygodnia. Z uwagi na prostotę można zamiast tego używać Zend_Date

Day

Zwraca zlokalizowaną listę dni tygodnia. Bez podania parametru zwracana jest zwykła lista pełnych nazw dni tygodnia wg. kalendarza gregoriańskiego ze skrótem angielskiej nazwy dnia tygodnia w kluczu i przetłumaczoną pełną nazwą dnia w wartości. Można uzyskać nazwy dni z innego kalendarza jeśli poda się tablicę w parametrze. Pierwszą wartością tej tablicy powinna być nazwa kalendarza, drugą - kontekst, trzecią - szerokość zwracanych danych. Z uwagi na prostotę można zamiast tego używać Zend_Date

Week | Zwraca listę wartości używanych przy obliczeniach dotyczących wygodni w ramach danego locale. Dla uproszczenia można korzystać z Zend_Date
Quarters | Zwraca zlokalizowaną listę wszystkich nazw kwartałów dla podanego locale. Istnieje szereg różnych zestawów nazw kwartałów - każdy z nich zwracany jest w osobnej tablicy zagnieżdżonej. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze.

Quarter

Zwraca zlokalizowaną listę nazw kwartałów dla danego locale. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego, gdzie numer porządkowy kwartału jest przechowywany w kluczu tablicy a przetłumaczona nazwa - w wartości. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się w parametrze tablicę zawierającą jego nazwę oraz szerokość łańcucha z nazwą żądanego kwartału.

Eras | Zwraca zlokalizowaną listę wszystkich nazw er (okresów) dla podanego locale. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze.

Era

Zwraca zlokalizowaną listę nazw er (okresów) dla podanego locale. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego, gdzie numer ery jest przechowywany w kluczu tablicy a przetłumaczona nazwa - w wartości. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się w parametrze tablicę zawierającą jego nazwę oraz szerokość łańcucha z nazwą żądanej ery.

Date

Zwraca zlokalizowaną listę wszystkich znanych formatów daty dla podanego locale. Nazwa formatu jest umieszczona w kluczu tablicy a sam format - w wartości. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze. Dla uproszczenia można korzystać z Zend_Date.

Time

Zwraca zlokalizowaną listę wszystkich znanych formatów czasu dla podanego locale. Nazwa formatu jest umieszczona w kluczu tablicy a sam format - w wartości. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze. Dla uproszczenia można korzystać z Zend_Date.

DateTime

Zwraca zlokalizowaną listę wszystkich znanych formatów daty i czasu dla podanego locale. Nazwa formatu jest umieszczona w kluczu tablicy a sam format - w wartości. Jeśli w parametrze nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze. Dla uproszczenia można korzystać z Zend_Date.

DateItem | Zwraca listę domyślnych formatów dla danej części daty lub czasu
DateInterval | Zwraca listę formatów daty i czasu, które są używane w przypadku wyświetlania różnic dat. Zwracana lista to wielowymiarowa tablica, gdzie pierwszym wymiarem jest format, drugim - składnik formatu o największej różnicy.
Field | Zwraca listę zlokalizowanych nazw części daty, które mogą zostać użyte do wyświetlenia kalendarza lub wyrazów takich jak 'miesiąc' czy 'rok' w odpowiednim języku. Jeśli nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze
Relative | Zwraca listę zlokalizowanych określeń relatywnych dat, których można użyć do wyświetlenia zwrotów typu 'wczoraj' czy 'jutro' w odpowiednim języku. Jeśli nie zostanie podana wartość to zwrócona lista będzie dotyczyć kalandarza gregoriańskiego. Można uzyskać listę dla innego systemu kalendarza jeśli przekaże się jego nazwę w parametrze
Symbols | Zwraca listę zlokalizowanych znaków używanych przy formatowaniu liczb.
NameToCurrency | Zwraca listę zlokalizowanych nazw walut. Kod waluty jest umieszczony w kluczu tablicy a przetłumaczona nazwa - w wartości. Dla uproszczenia można korzystać z Zend_Currency
CurrencyToName | Zwraca listę kodów walut wg. zlokalizowanych nazw walut. Przetłumaczona nazwa jest umieszczona w kluczu a kod waluty - w wartości. Dla uproszczenia można używać Zend_Currency
CurrencySymbol | Zwraca listę zlokalizowanych symboli walut. Kod waluty jest umieszczony w kluczu tablicy a symbol - w wartości. Dla uproszczenia można używać Zend_Currency
Question | Zwraca listę zlokalizowanych odpowiedzi oznaczających zgodę ('yes') oraz zaprzeczenie ('no'). Dla uproszczenia można używać metody getQuestion
CurrencyFraction | Zwraca listę ilości miejsc po przecinku dla walut. Kod waluty jest umieszczony w kluczu tablicy a ilość miejsc po przecinku - w wartości. Dla uproszczenia można używać Zend_Currency
CurrencyRounding | Zwraca listę sposobów zaokrąglenia dla walut. Kod waluty jest umieszczony w kluczu tablicy a ilość miejsc po przecinku do zaokrąglenia - w wartości. Dla uproszczenia można używać Zend_Currency
CurrencyToRegion | Zwraca listę walut wg. regionu, w którym obowiązują. Kod regionu `ISO3166` jest umieszczony w kluczu tablicy a kod waluty `ISO4217` - w wartości. Dla uproszczenia można używać Zend_Currency
RegionToCurrency | Zwraca listę regionów wg. obowiązującej waluty. Kod waluty `ISO4217` umieszczony jest w kluczu tablicy a kod regionu `ISO3166` - w wartości. Jeśli dana waluta jest używana w wielu regionach to są one oddzielone spacją. Dla uproszczenia można używać Zend_Currency
RegionToTerritory | Zwraca listę terytoriów z krajami lub subterytoriami, które są zawarte w nich. Kod ISO terytorium jest używany jako klucz tablicy a kod `ISO3166` kraju/subterytorium - jako wartości. Jeśli terytorium zawiera więcej niż jedno państwo/subterytorium to są one oddzielone spacją.
TerritoryToRegion | Zwraca listę krajów lub subterytoriów z terytoriami w których są zawarte. Kod `ISO3166` kraju/subterytorium jest używany jako klucz tablicy a kod ISO terytorium - jako wartości. Jeśli państwo/subterytorium wchodzi w skład więcej niż jednego terytorium to są one oddzielone spacją.
ScriptToLanguage | Zwraca listę systemów pisma, jakie są używane w ramach języka. Kod języka jest umieszczony w kluczu tablicy a kod systemu pisma - w wartości. Jeśli język posługuje się wieloma systemami to są one oddzielone spacją.
LanguageToScript | Zwraca listę języków i systemów pisma, jakie są używane w jego ramach. Kod systemu jest umieszczony w kluczu tablicy a kod języka - w wartości. Jeśli system jest używany w wielu językach to są one oddzielone spacją.
TerritoryToLanguage | Zwraca listę państw używających określonego języka. Kod państwa jest umieszczany w kluczu tablicy a kod języka - w wartości. Jeśli dany język jest używany w więcej niż jednym państwie to zostają one oddzielone spacją.
LanguageToTerritory | Zwraca listę języków i państw używających określonego języka. Kod języka jest umieszczany w kluczu tablicy a kod państwa - w wartości. Jeśli dane państwo używa więcej niż jednego języka zostają one oddzielone spacją.
TimezoneToWindows | Zwraca listę stref czasowych Windows i odpowiadających im stref czasowych ISO. Strefa Windows jest umieszczona w kluczu a strefa ISO - w wartości.
WindowsToTimezone | Zwraca listę stref czasowych ISO i odpowiadających im stref czasowych Windows. Strefa ISO jest umieszczona w kluczu a strefa Windows - w wartości.
TerritoryToTimezone | Zwraca listę terytoriów i związanych z nimi stref czasowych ISO. Strefa czasowa jest umieszczona w kluczu a kod terytorium (regionu) - w wartości.
TimezoneToTerritory | Zwraca listę stref czasowych ISO i związanych z nimi terytoriów. Kod terytorium (regionu) jest umieszczony w kluczu a strefa czasowa - w wartości.
CityToTimezone | Zwraca zlokalizowaną listę nazw miast, które mogą zostać użyte przy tłumaczeniu nazw stref czasowych. Lista nie jest dostępna dla wszystkich stref ale dla użytkownika może być ważniejsze wyszukanie przetłumaczonej nazwy konkretnego miasta niż nazwy ISO strefy czasowej. Nazwa ISO strefy jest umieszczona w kluczu a przetłumaczona nazwa miasta - w wartości.
TimezoneToCity | Zwraca zlokalizowaną listę nazw nazw stref czasowych i przetłumaczonych nazw miast. Miasto jest umieszczone w kluczu a strefa czasowa ISO - w wartości.
PhoneToTerritory | Zwraca listę telefonicznych kodów kierunkowych i terytoriów w których obowiązują. Nazwa terytorium (regionu) umieszczona jest w kluczu a kod kierunkowy - w wartości.
TerritoryToPhone | Zwraca listę terytoriów i ich telefonicznych kodów kierunkowych. Kod jest umieszczony w kluczu tablicy a nazwa terytorium (regionu) - w wartości. Jeśli dany kod jest używany w więcej niż jednym regionie są one oddzielone spacją.
NumericToTerritory | Zwraca listę 3-cyfrowych kodów odpowiadających terytoriom. Terytorium (region) jest umieszczany w kluczu a 3-cyfrowy kod - w wartości.
TerritoryToNumeric | Zwraca listę terytoriów z ich 3-cyfrowym kodem. 3-cyfrowy kod jest umieszczony w kluczu a nazwa terytorium (regionu) w wartości.
Alpha3ToTerritory | Zwraca listę 3-literowych kodów odpowiadających terytoriom. Terytorium (region) jest umieszczany w kluczu a 3-literowy kod - w wartości.
TerritoryToAlpha3 | Zwraca listę terytoriów z ich 3-literowym kodem. 3-literowy kod jest umieszczony w kluczu a nazwa terytorium (regionu) w wartości.
PostalToTerritory | Zwraca listę terytoriów z wyrażeniem regularnym sprawdzającym poprawność kodu pocztowego w danym terytorium. Kod ISO terytorium jest umieszczony w kluczu z regex - w wartości.
NumberingSystem | Zwraca listę systemów pisma z cyframi używanymi w danym systemie.
FallbackToChar | Zwraca listę znaków specjalnych i ich odpowiedników w unicode. Dzięki temu można np. zamienić "©" na "(C)".
CharToFallback | Zwraca listę znaków unicode dla często zastępowanych znaków. Dzięki temu można np. zamienić "(C)" na "©"
LocaleUpgrade | Zwraca listę zależności locale, co może zostać wykorzystane do rozwinięcia podanego języka do pełnego identyfikatora locale
Unit | Zwraca listę zlokalizowanych jednostek kalendarzowych. Dzięki temu można automatycznie przetłumaczyć łańcuchy takie jak "day", "month" itp.

Jeśli potrzebna jest pojedyncza przetłumaczona wartość można skorzystać z metody `getTranslation()`. Zawsze zwracany jest łańcuch znaków zaś przyjmowane argumenty są różne od tych przyjmowanych przez `getTranslationList()`. Parametr wartości jest taki sam jak wcześniej z jedną różnicą - identyfikator żądanego detalu musi zostać przekazany jako dodatkowy parametr.

Ponieważ wartość prawie zawsze musi być przekazana to staje się ona pierwszym parametrem. Jest to różnica w stosunku do metody `getTranslationList()`.

Poniżej przedstawiono tabelę zawierającą bardziej szczegółowe informacje:

### Szczegóły użycia metody getTranslation($value = null, $type = null, $locale = null)

Typ | Opis
--- | ---
Language | Zwraca tłumaczenie nazwy języka. Aby uzyskać żądane tłumaczenie należy w parametrze wartości przekazać kod języka
Script | Zwraca tłumaczenie nazwy systemu pisma. Aby uzyskać żądane tłumaczenie należy w parametrze wartości przekazać kod systemu pisma
Territory lub Country | Zwraca tłumaczenie nazwy terytorium. Mogą to być kraje, kontynenty i inne terytoria. Aby uzyskać żądane tłumaczenie należy w parametrze wartości przekazać kod terytorium
Variant | Zwraca tłumaczenie nazwy odmiany systemu pisma. Aby uzyskać żądane tłumaczenie należy w parametrze wartości przekazać kod żądanej odmiany
Key | Zwraca tłumaczenie nazw znanych kluczy. Są to generyczne wartości używane w tłumaczeniach oznaczające system kalendarza, porządek sortowania, walutę. Aby uzyskać żądane tłumaczenie należy w parametrze wartości przekazać kod klucza
DefaultCalendar | Zwraca domyślny system kalendarza dla podanego locale. Dla większości będzie to 'gregorian'. Dla uproszczenia można używać Zend_Date
MonthContext | Zwraca domyślny kontekst miesięcy, który jest używany w ramach podanego systemu kalendarza. Jeśli nie poda się nazwy kalendarza to zostanie użyta domyślna nazwa - 'gregorian'. Dla uproszczenia można korzystać z Zend_Date
DefaultMonth | Zwraca domyślny format miesięcy, który jest używany w ramach podanego systemu kalendarza. Jeśli nie poda się nazwy kalendarza to zostanie użyta domyślna nazwa - 'gregorian'. Dla uproszczenia można korzystać z Zend_Date

Month

Zwraca tłumaczenie nazwy miesiąca. Należy podać numer miesiąca w postaci liczby (w zakresie 1-12). Jeśli występuje potrzeba pobrania danych dla innego kalendarza, kontekstu czy formatu to przekazany argument musi być tablicą zawierającą oczekiwane dane. Tablica musi mieć następującą strukturę: `array( 'calendar', 'context', 'format', 'month number')`. W przypadku podania jedynie numeru miesiąca domyślnymi wartościami są kalendarz - 'gregorian', contekst - 'format', format - 'wide'. Dla uproszczenia można korzystać z Zend_Date

DayContext | Zwraca domyślny kontekst dni, który jest używany w ramach podanego systemu kalendarza. Jeśli nie poda się nazwy kalendarza to zostanie użyta domyślna nazwa - 'gregorian'. Dla uproszczenia można korzystać z Zend_Date
DefaultDay | Zwraca domyślny format dni, który jest używany w ramach podanego systemu kalendarza. Jeśli nie poda się nazwy kalendarza to zostanie użyta domyślna nazwa - 'gregorian'. Dla uproszczenia można korzystać z Zend_Date

Day

Zwraca tłumaczenie nazwy dnia tygodnia. Należy podać angielski skrót żądanego dnia tygodnia w postaci łańcucha znaków ('sun', 'mon', itp.). Jeśli występuje potrzeba pobrania danych dla innego kalendarza, kontekstu czy formatu to przekazany argument musi być tablicą zawierającą oczekiwane dane. Tablica musi mieć następującą strukturę: `array( 'calendar', 'context', 'format','day abbreviation')`. W przypadku podania jedynie skrótu dnia domyślnymi wartościami są kalendarz - 'gregorian', contekst - 'format', format - 'wide'. Dla uproszczenia można korzystać z Zend_Date

Quarter

Zwraca tłumaczenie nazwy kwartału. Należy podać numer kwartału w postaci liczby całkowitej (w zakresie 1-4). Jeśli występuje potrzeba pobrania danych dla innego kalendarza, kontekstu czy formatu to przekazany argument musi być tablicą zawierającą oczekiwane dane. Tablica musi mieć następującą strukturę: `array( 'calendar', 'context', 'format','quarter number')`. W przypadku podania jedynie numeru kwartału domyślnymi wartościami są kalendarz - 'gregorian', contekst - 'format', format - 'wide'

Am | Zwraca tłumaczenie 'AM' dla podanego locale. Jeśli występuje potrzeba pobrania danych dla innego kalendarza, należy podać jego nazwę w argumencie. Bez podania nazwy zostanie użyty kalendarz gregoriański. Dla uproszczenia można korzystać z Zend_Date
Pm | Zwraca tłumaczenie 'AM' dla podanego locale. Jeśli występuje potrzeba pobrania danych dla innego kalendarza, należy podać jego nazwę w argumencie. Bez podania nazwy zostanie użyty kalendarz gregoriański. Dla uproszczenia można korzystać z Zend_Date

Era

Zwraca tłumaczenie nazwy ery. Należy podać numer ery w postaci liczby całkowitej. Jeśli występuje potrzeba pobrania danych dla innego kalendarza czy formatu to przekazany argument musi być tablicą zawierającą oczekiwane dane. Tablica musi mieć następującą strukturę: `array('calendar', 'format','era number')`. W przypadku podania jedynie numeru kwartału domyślnymi wartościami są kalendarz - 'gregorian', format - 'abbr'

DefaultDate | Zwraca domyślny format daty używany w ramach danego kalendarza. Bez podania nazwy zostanie użyty kalendarz gregoriański. Dla uproszczenia można korzystać z Zend_Date
Date | Zwraca format daty dla danego kalendarza lub format w ramach locale. Bez podania nazwy zostanie użyty kalendarz gregoriański z formatem 'medium'. Jeśli zostanie podana nazwa w łańcuchu wtedy użyty będzie kalendarz gregoriański z formatem o podanej nazwie. Można podać również tablicę o strukturze: `array('calendar','format')`. Dla uproszczenia można korzystać z Zend_Date
DefaultTime | Zwraca domyślny format czasu w ramach danego kalendarza. Bez podania nazwy zostanie użyty kalendarz gregoriański. Dla uproszczenia można korzystać z Zend_Date
Time | Zwraca format czasu dla danego kalendarza lub format w ramach locale. Bez podania nazwy zostanie użyty kalendarz gregoriański z formatem 'medium'. Jeśli zostanie podana nazwa w łańcuchu wtedy użyty będzie kalendarz gregoriański z formatem o podanej nazwie. Można podać również tablicę o strukturze: `array('calendar','format')`. Dla uproszczenia można korzystać z Zend_Date
DateTime | Zwraca format daty i czasu dla danego locale, co wskazuje na sposób reprezentowania daty z czasem w jednym łańcuchu znaków w ramach danego kalendarza. Bez podania nazwy zostanie użyty kalendarz gregoriański. Dla uproszczenia można korzystać z Zend_Date
DateItem | Zwraca domyślny format dla podanej części daty lub czasu
DateInterval | Zwraca format różnicy dla podanego formatu daty lub czasu. Pierwszą wartością jest nazwa kalendarza, przeważnie 'gregorian'. Drugą wartością format daty lub czasu a trzecią - część formatu o największej różnicy. Dla przykładu: array('gregorian', 'yMMMM', 'y') zwróci format różnicy dla formatu daty 'yMMMM' gdzie 'y' ma największą różnicę.
Field | Zwraca zlokalizowany element daty, co może zostać wykorzystane do wyświetlania łańcuchów takich jak 'miesiąc' czy 'rok' przetłumaczonych na podany język. Element, który ma zostać przetłumaczony musi być podany w argumencie. Domyślnie użyty będzie kalendarz gregoriański. Aby skorzystać z innego systemu kalendarza należy podać tablicę o poniższej strukturze: `array('calendar', 'date field')`

Relative

Zwraca przetłumaczoną, relatywną datę w stosunku do obecnej chwili. Wynik może zawierać łańcuchy znaków takie jak 'wczoraj' czy 'jutro' w podanym języku. W argumencie należy podać ilość dni w stosunku do bieżącego dnia. Dla dnia poprzedniego będzie to '-1', dla następnego - '1' itp. Domyślnie użyty będzie kalendarz gregoriański. Aby skorzystać z innego systemu kalendarza należy podać tablicę o poniższej strukturze: `array('calendar', 'relative days')` Dla uproszczenia można korzystać z Zend_Date

DecimalNumber | Zwraca format liczb dziesiętnych obowiązujący w danym locale. Dla uproszczenia można korzystać z Zend_Locale_Format
ScientificNumber | Zwraca naukowy format liczb obowiązujący w danym locale
PercentNumber | Zwraca format liczb procentowych obowiązujący w danym locale
CurrencyNumber | Zwraca format używany do reprezentacji kwot walut obowiązujący w danym locale. Dla uproszczenia można korzystać z Zend_Currency
NameToCurrency | Zwraca przetłumaczoną nazwę podanej waluty. Waluta musi być podana w formacie ISO. Np.: 'EUR' dla waluty 'euro'. Dla uproszczenia można korzystać z Zend_Currency
CurrencyToName | Zwraca walutę dla podanej zlokalizowanej nazwy Dla uproszczenia można korzystać z Zend_Currency
CurrencySymbol | Zwraca symbol waluty używanej w ramach podanego locale. Nie wszystkie waluty mają swój symbol. Dla uproszczenia można korzystać z Zend_Currency
Question | Zwraca zlokalizowane łańcuchy znaków oznaczające potwierdzenie lub zaprzeczenie. Należy podać 'yes' lub 'no' jako parametr aby otrzymać odpowiednie tłumaczenie. Dla uproszczenia można korzystać z Zend_Locale::getQuestion
CurrencyFraction | Zwraca część składową danej waluty. Waluta musi być podana w formacie ISO. Np.: 'EUR' dla waluty 'euro'. Dla uproszczenia można korzystać z Zend_Currency
CurrencyRounding | Zwraca format zaokrąglenia danej waluty. Waluta musi być podana w formacie ISO. Np.: 'EUR' dla waluty Euro. Jeśli nie poda się nazwy to zostanie użyte zaokrąglenie 'DEFAULT'. Dla uproszczenia można korzystać z Zend_Currency
CurrencyToRegion | Zwraca walutę dla podanego regionu. Kod regionu musi być podany w formie łańcucha znaków `ISO3166`. Np.: 'AT' dla Austrii. Dla uproszczenia można korzystać z Zend_Currency
RegionToCurrency | Zwraca listę regionów, gdzie dana waluta jest używana. Kod waluty musi być podany w formie łańcucha znaków `ISO4217`. Np.: 'EUR' dla Euro. Jeśli waluta jest używana w wielu regionach to zostaną one oddzielone spacją. Dla uproszczenia można korzystać z Zend_Currency
RegionToTerritory | Zwraca listę regionów danego terytorium. Terytorium powinno być podane jako łańcuch znaków standardu `ISO4217` (np. '001' oznacza 'cały świat'). Nazwy zwracanych regionów są oddzielone spacją
TerritoryToRegion | Zwraca terytoria lokalizacji podanego regionu. Region powinien być podany jako łańcuch znaków standardu `ISO3166` (np. 'AT' - Austria). Jeśli region rozciąga się na wiele terytoriów to ich nazwy oddzielone są spacją
ScriptToLanguage | Zwraca systemy pisma używane w ramach danego locale. Język musi być podany w formie kodu ISO (np. 'en' - angielski). Jeśli dany język używa więcej niż jednego systemu pisma to ich nazwy oddzielone są spacją
LanguageToScript | Zwraca języki używające danego systemu pisma. System pisma musi być podany w formie kodu ISO (np. 'Latn' - Łacina). Jeśli systemu pisma jest używany przez więcej niż jeden język to ich nazwy oddzielone są spacją
TerritoryToLanguage | Zwraca terytoria gdzie dany język jest używany. Język musi być podany w formie kodu ISO (np. 'en' - angielski). Jeśli dany język jest używany przez więcej niż jedno terytorium to ich nazwy oddzielone są spacją
LanguageToTerritory | Zwraca listę języków danego terytorium. Terytorium powinno być podane jako łańcuch znaków standardu `ISO3166` (np. 'IT' oznacza Włochy). Jeśli na danym terytorium używa się więcej niż jednego języka to ich nazwy oddzielone są spacją
TimezoneToWindows | Zwraca strefę czasową ISO odpowiadającą strefie czasowej Windows
WindowsToTimezone | Zwraca strefę czasową Windows odpowiadającą strefie czasowej ISO
TerritoryToTimezone | Zwraca terytorium odpowiadające danej strefie czasowej ISO
TimezoneToTerritory | Zwraca strefę czasową ISO odpowiadającą danemu terytorium
CityToTimezone | Zwraca zlokalizowaną nazwę miasta odpowiadającą danej strefie czasowej ISO. Nie wszystkie strefy mają przypisaną przetłumaczoną nazwę miasta
TimezoneToCity | Zwraca strefę czasową ISO odpowiadającą podanej, zlokalizowanej nazwie miasta. Nie wszystkie miasta mają przypisaną strefę czasową
PhoneToTerritory | Zwraca kod telefoniczny odpowiadający podanemu terytorium (regionowi). Kod terytorium musi być podany w standardzie `ISO3166` (np. 'AT' - Austria)
TerritoryToPhone | Zwraca terytorium (region) na którym obowiązuje podany kod telefoniczny. Kod musi być podany w postaci cyfr (np. '43' zamiast '+43'). Jeśli dany kod jest używany na wielu terytoriach to ich nazwy oddzielone są spacją
NumericToTerritory | Zwraca 3-cyfrowy kod podanego terytorium (regionu). Nazwa terytorium musi być podana w standardzie `ISO3166` (np. 'AT' oznacza Austrię)
TerritoryToNumeric | Zwraca terytorium (region) odpowiadający podanemu 3-cyfrowemu kodowi. Kod musi być podany w postaci samych cyfr (np. '43')
Alpha3ToTerritory | Zwraca 3-znakowy kod podanego terytorium (regionu). Nazwa terytorium musi być podana w standardzie `ISO3166` (np. 'AT' dla Austrii)
TerritoryToAlpha3 | Zwraca terytorium (region) odpowiadający danemu 3-znakowemu kodowi
PostalToTerritory | Zwraca wzór wyrażenia regularnego odpowiadającego kodowi pocztowemu dla podanego terytorium. Nazwa terytorium musi być podana w standardzie `ISO4217` (np. '001' - Świat)
NumberingSystem | Zwraca znaki oznaczające cyfry w ramach podanego systemu pisma
FallbackToChar | Zwraca znaki zastępujące często używany specjalny znak unicode. Można tego użyć do zastąpienia "©" za pomocą "(C)"
CharToFallback | Zwraca specjalny znak unicode dla podanego łańcucha zastępującego. Można tego użyć do zastąpienia "(C)" za pomocą "©"
LocaleUpgrade | Zwraca nazwę zależnego locale, dla locale podanego. Dzięki temu można uzyskać pełną nazwę poprawnego locale
Unit | Zwraca zlokalizowaną nazwę jednostki kalendarza. Dzięki temu można automatycznie uzyskać tłumaczenie łańcuchów "dzień", "miesiąc" itp. Pierwszym parametrem musi być typ a drugim - liczba

Z nadejściem Zend Framework 1.5 wiele starszych typów zostało przemianowanych. Zostało to wymuszone przez wprowadzenie szeregu nowych typów i występowanie błędów w starych nazwach. Zmiany te zwiększają użyteczność powyższych metod. Poniżej znajduje się lista zmian:

### Różnica pomiędzy Zend Framework 1.0 oraz 1.5

Stary typ | Nowy typ
--- | ---
Country | Territory (z wartością '2')
Calendar | Type (z wartością 'calendar')
Month_Short | Month (z tablicą array('gregorian', 'format', 'abbreviated')
Month_Narrow | Month (z tablicą array('gregorian', 'stand-alone', 'narrow')
Month_Complete | Months
Day_Short | Day (z tablicą array('gregorian', 'format', 'abbreviated')
Day_Narrow | Day (z tablicą array('gregorian', 'stand-alone', 'narrow')
DateFormat | Date
TimeFormat | Time
Timezones | CityToTimezone
Currency | NameToCurrency
Currency_Sign | CurrencySymbol
Currency_Detail | CurrencyToRegion
Territory_Detail | TerritoryToRegion
Language_Detail | LanguageToTerritory

Poniższy przykład pokazuje sposób pozyskania określonych nazw w żądanym języku.

### getTranslationList

    // wyświetla nazwy wszystkich krajów w języku niemieckim
    print_r(Zend_Locale::getTranslationList('country', 'de'));

Następny przykład pokazuje sposób odnalezienia nazwy locale w innym języku, jeśli nieznany jest kod ISO kraju.

### Zamiana nazwy kraju z jednego języka na drugi

    $code2name = Zend_Locale::getLanguageTranslationList('en_US');
    $name2code = array_flip($code2name);
    $frenchCode = $name2code['French'];
    echo Zend_Locale::getLanguageTranslation($frenchCode, 'de_AT');
    // na wyjściu znajduje się nazwa języka francuskiego po niemiecku

Aby wygenerować listę wszystkich języków znanych przez `Zend_Locale`, z każdą nazwą w oryginalnej formie można skorzystać z poniższego przykładu. Podobnie metody `getCountryTranslationList()` oraz `getCountryTranslation()` mogą zostać użyte do utworzenia tabeli mapującej nazwy regionów w języku użytkownika do nazw regionów w innym języku. Aby wyłapać wyjątki spowodowane przez nieistniejące locale należy użyć konstrukcji `try .. catch`. Nie wszystkie języki stanowią locale. W poniższym przykładzie wyjątki są ignorowane aby zapobiec przedwczesnemu zakończeniu skryptu.

### Nazwy wszystkich języków w oryginalnym brzmieniu

    $list = Zend_Locale::getLanguageTranslationList('auto');

    foreach($list as $language => $content) {
        try {
            $output = Zend_Locale::getLanguageTranslation($language, $language);
            if (is_string($output)) {
                print "\n<br>[".$language."] ".$output;
            }
        } catch (Exception $e) {
            continue;
        }
    }

## Uzyskanie tłumaczenia dla "yes" oraz "no"

Często może dochodzić do sytuacji, w której niezbędne jest uzyskanie od użytkownika odpowiedzi "tak" lub "nie". Aby uzyskać tablicę zawierającą odpowiednie słowa lub wyrażenia regularne w zależności od określonego locale (domyślnie jest to locale bieżącego obiektu) należy użyć metody `getQuestion()`. Tablica zwrotna zawiera następujące dane:

- yes and no: Generyczny łańcuch znaków z odpowiedziami oznaczającymi zgodę oraz odmowę. Będzie to najprostszy element tablicy yesarray oraz noarray.

  yesarray and noarray: Tablica ze wszystkimi znanymi odpowiedziami oznaczającymi zgodę oraz odmowę. Wiele języków posiada więcej niż jeden zestaw odpowiedzi. Generalnie zawarte są tu pełne odpowiedzi oraz skróty.

  yesexpr and noexpr: Wyrażenie regularne ułatwiające odpowiednie zakwalifikowanie odpowiedzi dostarczonej przez użytkownika oraz wyszukanie odpowiedzi oznaczających zgodę oraz odmowę.

Wszystkie powyższe informacje są zlokalizowane. Poniższy przykład przedstawia zestaw danych, jakie można otrzymać:

### getQuestion()

    $locale = new Zend_Locale();
    // Łańcuchy ze zgodą oraz odmową
    print_r($locale->getQuestion('de'));

    - - - Output - - -

    Array
    (
        [yes] => ja
        [no] => nein
        [yesarray] => Array
            (
                [0] => ja
                [1] => j
            )

        [noarray] => Array
            (
                [0] => nein
                [1] => n
            )

        [yesexpr] => ^([jJ][aA]?)|([jJ]?)
        [noexpr] => ^([nN]([eE][iI][nN])?)|([nN]?)
    )

Do wersji 1.0.3 była dostępna również tablica yesabbr. Od 1.5 te informacje nie są dostępne bezpośrednio ale można je odnaleźć w yesarray.

## Uzyskanie listy wszystkich znanych locale

Może nastąpić sytuacja w której niezbędne okaże się uzyskanie listy wszystkich znanych locale. Może to być użyteczne przy wielu czynnościach jak np. utworzenie listy wyboru. Aby to osiągnąć należy użyć statycznej metody `getLocaleList()`.

### getLocaleList()

    $localelist = Zend_Locale::getLocaleList();

Należy zwrócić uwagę na fakt iż nazwy locale znajdują się w kluczach tablicy zwrotnej. Wartości każdego jej elementu to boolean `TRUE`.

## Rozpoznanie locale

Jeśli zaistnieje potrzeba rozpoznania czy dana zmienna, niezależnie z jakiego źródła pochodzi, jest poprawnym locale można do tego celu użyć statycznej metody `isLocale()`. Jej pierwszy parametr to łańcuch znaków do sprawdzenia.

### Proste rozpoznanie locale

    $input = 'to_RU';
    if (Zend_Locale::isLocale($input)) {
        print "'{$input}' to poprawne locale";
    } else {
        print "Niestety... podana zmienna nie jest poprawnym locale";
    }

Jak widać, powyższa metoda zawsze zwraca wartość logiczną. Istnieje jeden powód, który powoduje rzucenie wyjątku w tej metodzie. Dzieje się tak jeśli system operacyjny nie dostarcza żadnego locale a Zend Framework nie jest w stanie go wykryć automatycznie. Często może to oznaczać problem istniejący na styku systemu i środowiska PHP i jego funkcji `setlocale()`.

Należy też zauważyć, iż każdy podany łańcuch locale zostanie automatycznie ograniczony do kodu języka jeśli kod regionu nie jest poprawny. W poprzednim przykładzie kod języka `'to'` nie istnieje w regionie `'RU'` ale klasa `Zend_Locale` zwróci `TRUE` ponieważ możliwe jest dostosowanie podanego stringu do poprawnego locale.

Niekiedy, przydatne może okazać się ograniczenie wyżej opisanego zachowania. W takiej sytuacji należy skorzystać z drugiego parametru metody `isLocale()`. Parametr `strict` przyjmuje domyślnie wartość `FALSE` ale można zadeklarować jego wartość jako `TRUE` i wyłączyć dostosowywanie przekazanego locale.

### Ścisłe rozpoznanie locale

    $input = 'to_RU';
    if (Zend_Locale::isLocale($input, true)) {
        print "'{$input}' to poprawne locale";
    } else {
        print "Niestety... podana zmienna nie jest poprawnym locale";
    }

Teraz, kiedy możliwe jest rozpoznanie czy określony łańcuch znaków jest poprawnym locale, nic nie stoi na przeszkodzie aby samemu tworzyć klasy świadome locale. Jednak wprowadzając podobne rozwiązanie szybko dochodzi się do wniosku, że implementacja będzie stanowiła bardzo podobne 15 linijek kodu. Przykładowo:

### Implementacja kodu świadomego locale

    if ($locale === null) {
        $locale = new Zend_Locale();
    }

    if (!Zend_Locale::isLocale($locale, true, false)) {
        if (!Zend_Locale::isLocale($locale, false, false)) {
            throw new Zend_Locale_Exception(
                "The locale '$locale' is no known locale");
        }

        $locale = new Zend_Locale($locale);
    }

    if ($locale instanceof Zend_Locale) {
        $locale = $locale->toString();
    }

Z nadejściem Zend Framework 1.8 dodano statyczną metodę `findLocale()`, która zwraca łańcuch znaków zawierający locale. Oto lista jej zadań:

- Sprawdzenie czy podany string jest poprawnym locale

- Ograniczenie locale jeśli region nie jest poprawny

- Zwrócenie uprzednio ustawionego locale aplikacji w przypadku braku argumentów

- Sprawdzenie locale pobranego z przeglądarki jeśli wcześniejsze detekcje zawiodły

- Sprawdzenie locale środowiska serwera jeśli wcześniejsze detekcje zawiodły

- Sprawdzenie locale frameworka jeśli wcześniejsze detekcje zawiodły

- Zwrócenie łańcucha znaków reprezentującego znalezione locale

Poniższy przykład pokazuje sposób użycia tej metody zamiast, wcześniej opisanych, kilkunastu linijek:

### Implementacja kodu świadomego locale z Zend Framework 1.8

    $locale = Zend_Locale::findLocale($inputstring);