Wstęp

W dzisiejszym globalnym świecie, coraz więcej aplikacji internetowych musi obsługiwać różne języki i lokalizacje, aby dotrzeć do szerokiej gamy użytkowników na całym świecie. W tym artykule omówimy, jak skonfigurować i zaimplementować internacjonalizację (i18n) w ramach Symfony 6.2, jednym z najpopularniejszych frameworków PHP. Dzięki temu będziemy mogli obsługiwać tłumaczenia stron w sposób bardziej elastyczny i automatyczny, co pozwoli na lepsze zarządzanie procesem tłumaczeń w naszej aplikacji.

Symfony 6.2 oferuje wyjątkowe wsparcie dla internacjonalizacji, umożliwiając automatyczne rozpoznawanie języka ustawionego w przeglądarce użytkownika. Dzięki temu, nasza aplikacja będzie domyślnie wysyłać tłumaczenia stron w języku preferowanym przez użytkownika, co z pewnością zwiększy komfort korzystania z serwisu.

Jednocześnie, Symfony 6.2 umożliwia uzyskiwanie tłumaczeń poprzez trasę. To oznacza, że użytkownik będzie mógł zmieniać język na żądanie, wpisując odpowiedni kod języka (np. /pl lub /en) w pasku adresu przeglądarki. Funkcja ta jest niezwykle przydatna dla osób, które chcą szybko przełączać między różnymi językami lub dla serwisów, które chcą świadczyć usługi w kilku językach na różnych rynkach.

W dalszej części artykułu przyjrzymy się dokładniej mechanizmom Symfony 6.2 odpowiedzialnym za internacjonalizację, a także pokażemy, jak skonfigurować i zaimplementować te funkcje w praktyce. Dzięki temu, będziesz mógł stworzyć wielojęzyczną aplikację, która będzie przyjazna dla użytkowników z całego świata, obsługując szeroki wachlarz tłumaczeń.

Instalacja pakietu symfony/translation

Aby rozpocząć pracę nad internacjonalizacją naszej aplikacji, musimy zainstalować pakiet symfony/translation. Służy do tego polecenie:

composer require symfony/translation

Pakiet ten dostarcza niezbędnych narzędzi i komponentów do obsługi tłumaczeń w naszym projekcie.

Konfiguracja frameworka

Po zainstalowaniu pakietu symfony/translation, musimy dostosować konfigurację frameworka. W pliku config/packages/framework.yaml dodajemy następujące linie:

framework:
    // ...
    set_locale_from_accept_language: true
    set_content_language_from_locale: true
    enabled_locales: ['pl', 'en']

Te ustawienia mają następujące funkcje:

• set_locale_from_accept_language: true – automatycznie ustawia lokalizację (język) na podstawie nagłówka „Accept-Language” przeglądarki użytkownika,
• set_content_language_from_locale: true – ustawia odpowiedni nagłówek „Content-Language” w odpowiedzi serwera, na podstawie wybranej lokalizacji,
• enabled_locales: ['pl', 'en'] – definiuje listę obsługiwanych języków (w tym przypadku polski i angielski).

Konfiguracja tłumaczeń

Następnie konfigurujemy tłumaczenia, dodając poniższy fragment do pliku config/packages/translation.yaml:

framework:
    default_locale: pl

Wprowadzone ustawienie default_locale: pl oznacza, że domyślnym językiem naszej aplikacji będzie polski.

Konfiguracja tras

Ostatnim krokiem jest konfiguracja tras, dzięki której użytkownik będzie mógł wybrać język za pomocą odpowiedniego prefixu w adresie URL. W pliku config/routes.yaml dodajemy następujący kod:

app_i18n:
    resource: '../src/Controller/'
    type: annotation
    prefix:
        en: '/en'
        pl: '/pl'
    requirements:
        _locale: 'en|pl'
    defaults:
        _locale: 'pl'

Ten fragment konfiguracji pozwala na definiowanie języka poprzez prefixy w adresie URL (np. „/en” lub „/pl”). Zdefiniowane są także wymagania dotyczące wartości _locale, ograniczając je do obsługiwanych języków (w tym przypadku „en” i „pl”).

Dodawanie plików tłumaczeń

Po skonfigurowaniu internacjonalizacji w Symfony 6.2, kolejnym krokiem jest dodanie plików tłumaczeń do naszego projektu. Pliki te będą przechowywane w katalogu translations w głównym folderze aplikacji.

W celu zorganizowania tłumaczeń, tworzymy dwa pliki w katalogu translations:

1. messages.pl.yaml – zawierający tłumaczenia na język polski,
2. messages.en.yaml – zawierający tłumaczenia na język angielski.

W każdym z tych plików dodajemy odpowiednie klucze z tłumaczeniami. Na przykład, jeśli chcemy przetłumaczyć tekst „hello.world”, dodajemy następujące wpisy:

W pliku messages.pl.yaml:

hello.world: 'Witaj, świecie!'

W pliku messages.en.yaml:

hello.world: 'Hello, world!'

Takie podejście pozwala na łatwe zarządzanie tłumaczeniami w naszej aplikacji. Wystarczy dodać odpowiednie klucze do plików językowych, a Symfony automatycznie wykorzysta te tłumaczenia w zależności od wybranej lokalizacji.

Dodawanie trasy do kontrolera wykorzystującego tłumaczenia

Poniżej znajduje się kod kontrolera z dodaną trasą:

use Symfony\Contracts\Translation\TranslatorInterface;

#[Route('/indexTest', name: 'app_test')]
public function index(TranslatorInterface $translator): Response
{
    $translatedText = $translator->trans('hello.world');

    return new Response($translatedText);
}

Teraz omówimy, co się dzieje w tym fragmencie kodu:

1. use Symfony\Contracts\Translation\TranslatorInterface; – importujemy interfejs TranslatorInterface, który jest odpowiedzialny za tłumaczenie tekstu w naszej aplikacji.
2. #[Route('/test', name: 'app_test')] – definiujemy nową trasę o nazwie app_test, która będzie dostępna pod adresem /test. W przypadku korzystania z prefiksów językowych, trasa będzie dostępna pod adresem /pl/test oraz /en/test dla odpowiednio polskiej i angielskiej wersji językowej.
3. public function index(TranslatorInterface $translator): Response – w metodzie index kontrolera, wstrzykujemy zależność TranslatorInterface. Dzięki temu będziemy mogli korzystać z funkcji tłumaczących tekst w naszym kontrolerze.
4. $translatedText = $translator->trans('hello.world'); – używamy metody trans() na obiekcie $translator, aby przetłumaczyć tekst na podstawie klucza hello.world. Tłumaczenie zostanie automatycznie pobrane z odpowiedniego pliku językowego (messages.pl.yaml lub messages.en.yaml) na podstawie aktualnie wybranej lokalizacji.
5. return new Response($translatedText); – na koniec, zwracamy obiekt Response z przetłumaczonym tekstem. W zależności od ustawień językowych użytkownika, zostanie wyświetlony odpowiedni tekst: „Witaj, świecie!” dla języka polskiego lub „Hello, world!” dla języka angielskiego.

Dzięki zastosowaniu opisanego podejścia, nasza aplikacja będzie obsługiwać tłumaczenia na poziomie kontrolerów, co pozwoli na dynamiczną zmianę treści w zależności od wybranego języka. W kolejnych częściach artykułu omówimy także, jak korzystać z tłumaczeń w szablonach oraz jak zarządzać tłumaczeniami w bardziej zaawansowanych przypadkach.

Możemy teraz przetestować tłumaczenia:
http://symfony.local/pl/test
http://symfony.local/en/test
http://symfony.local/test

Aby przetestować trzecią trasę należy w przeglądarce zmienić język: Ustawienia/Język/Preferowany język i przenosimy interesujący nas język na górę. Następnie odświeżamy stronę i treść strony zmienia się na wybrany język.

Dodawanie trasy do kontrolera, która renderuje widok z wykorzystaniem tłumaczeń

Oto kod kontrolera z dodaną trasą:

#[Route('/test-view', name: 'app_test_view')]
public function indexTestView(): Response
{
    return $this->render('test/index.html.twig', [
        'controller_name' => 'TestController',
    ]);
}

W powyższym fragmencie kodu:

1. #[Route('/test-view', name: 'app_test_view')] – definiujemy nową trasę o nazwie app_test_view, która będzie dostępna pod adresem /test-view. Analogicznie do poprzedniego przykładu, trasa będzie dostępna również z prefiksami językowymi /pl/test-view oraz /en/test-view.
2. W metodzie indexTestView, zamiast korzystać z obiektu Response, używamy metody render() do wyświetlenia szablonu test/index.html.twig. Jako drugi argument przekazujemy tablicę z danymi, które chcemy przekazać do szablonu. W tym przypadku przekazujemy jedynie nazwę kontrolera.

Teraz omówimy szablon test/index.html.twig, który korzysta z tłumaczeń:

{% extends 'base.html.twig' %}

{% block title %}{{ 'hello.world'|trans }}{% endblock %}

{% block body %}
    {{ 'hello.world'|trans }}
{% endblock %}

W szablonie:

1. {% extends 'base.html.twig' %} – rozszerzamy szablon bazowy (base.html.twig), aby korzystać z jego struktury i bloków.
2. {% block title %}{{ 'hello.world'|trans }}{% endblock %} – definiujemy zawartość bloku title. Używamy filtru trans do tłumaczenia klucza hello.world. W zależności od ustawień językowych użytkownika, w tytule strony pojawi się „Witaj, świecie!” lub „Hello, world!”.
3. {% block body %}{{ 'hello.world'|trans }}{% endblock %} – definiujemy zawartość bloku body. Podobnie jak w bloku title, używamy filtru trans do tłumaczenia klucza hello.world. Tekst zostanie wyświetlony w ciele strony zgodnie z aktualnym językiem użytkownika.

Dzięki zastosowaniu przedstawionego podejścia, możemy łatwo korzystać z tłumaczeń w naszych szablonach Twig. W zależności od wybranego języka, Symfony automatycznie wybierze odpowiednie tłumaczenie na podstawie kluczy i plików językowych, co pozwoli na dynamiczną zmianę treści w naszej aplikacji.

Sprawdzenie istniejących tras

Uruchamiamy polecenie:

php bin/console debug:router

Polecenie to jest używane do wyświetlenia informacji na temat zarejestrowanych tras w projekcie Symfony. Daje ono możliwość sprawdzenia, czy trasy są poprawnie skonfigurowane, jak również pozwala na zrozumienie, w jaki sposób aplikacja przetwarza żądania URL.

Po uruchomieniu polecenia, otrzymujemy następujący wynik:

 -------------------------------- -------- -------- ------ -----------------------------------
  Name                             Method   Scheme   Host   Path
 -------------------------------- -------- -------- ------ -----------------------------------

  app_test                         ANY      ANY      ANY    /test
  app_test_view                    ANY      ANY      ANY    /test-view
  app_test.en                      ANY      ANY      ANY    /en/test
  app_test.pl                      ANY      ANY      ANY    /pl/test
  app_test_view.en                 ANY      ANY      ANY    /en/test-view
  app_test_view.pl                 ANY      ANY      ANY    /pl/test-view

Z wyników tego polecenia możemy zauważyć, że oprócz podstawowych tras /test i /test-view, dostępne są także warianty z prefiksami językowymi /en i /pl. Oznacza to, że konfiguracja internacjonalizacji zadziałała poprawnie, a nasza aplikacja obsługuje różne wersje językowe tras.

Podsumowanie

Podsumowując, w tym artykule przedstawiliśmy, jak skonfigurować internacjonalizację w Symfony 6.2, aby obsługiwać różne wersje językowe naszej aplikacji. Omówiliśmy kolejne kroki, od instalacji pakietu symfony/translation, przez konfigurację plików YAML, po dodawanie plików tłumaczeń i wykorzystanie tłumaczeń w kontrolerach oraz szablonach Twig.

Dzięki opisanym podejściom, możemy stworzyć aplikacje, które będą dynamicznie dostosowywać treść do preferencji językowych użytkownika, co pozwoli na lepsze zrozumienie i większą satysfakcję z korzystania z naszego oprogramowania. Ponadto, zarządzanie tłumaczeniami w oddzielnych plikach językowych ułatwia utrzymanie aplikacji oraz ewentualne wprowadzanie zmian w przyszłości.