# Tłumaczenia

Blockstudio dołącza tłumaczenia w folderze `languages`. WordPress używa ich, gdy język witryny lub język wybrany w profilu użytkownika odpowiada jednemu z nich. Działa to tak samo, gdy Blockstudio działa jako wtyczka, wtyczka typu must-use lub pakiet Composer.

## Dostępne języki

Blockstudio zawiera tłumaczenia dla języków i regionów WordPress zapisanych w dołączonym `languages/locales.json`, w tym wariantów regionalnych oraz formalnych i nieformalnych. Angielski (`en_US`) jest językiem źródłowym i nie wymaga pliku tłumaczenia. Lista łączy języki obsługiwane przez WordPress w GlotPress z wariantami dostępnymi w tłumaczeniach rdzenia WordPress API.

Istniejące tłumaczenia na niemiecki (`de_DE`) i formalny niemiecki (`de_DE_formal`) zostały zachowane. Dodatkowe tłumaczenia wygenerowano za pomocą GPT-6 Luna i oznaczono jako wygenerowane maszynowo w nagłówkach `.po`. Przechodzą automatyczne kontrole kompletności i formatu, ale nie wszystkie zostały sprawdzone przez rodzimych użytkowników języka. Zachęcamy do zgłaszania poprawek.

Tłumaczenia obejmują kontrolki pól w edytorze blokowym, stronę administracyjną, obszar roboczy, nakładkę narzędzi deweloperskich i komunikaty punktów końcowych REST. Etykiety i teksty pomocy we własnych plikach `block.json` należą do motywu lub wtyczki i korzystają z ich domeny tekstowej.

Wybierz język w **Ustawienia > Ogólne > Język witryny** albo ustaw język osobisty w profilu WordPress. Blockstudio automatycznie używa wybranego języka. Nie dodaje języków do selektora języka WordPress: dany język musi być również dostępny w instalacji WordPress. Witryna nie wymaga żądań do AI, subskrypcji tłumaczeń ani dodatkowych ustawień środowiska wykonawczego.

## Zastąp tłumaczenie

Pliki tłumaczeń w `wp-content/languages/plugins` mają pierwszeństwo przed dołączonymi plikami zarówno w przypadku ciągów PHP (`blockstudio-de_DE.mo` lub `blockstudio-de_DE.l10n.php`), jak i skryptów (osobny plik dla każdego identyfikatora skryptu, na przykład `blockstudio-de_DE-blockstudio-blocks.json`).

## Współtwórz tłumaczenie

Każdy język to plik `.po`, który możesz edytować w dowolnym edytorze tekstu lub narzędziu do tłumaczenia, takim jak Poedit. Zachęcamy do zgłaszania poprawek i nowych języków jako pull requestów.

1. Aby dodać język, skopiuj `languages/blockstudio.pot` do `languages/blockstudio-<locale>.po`, na przykład `blockstudio-fr_FR.po`, i ustaw nagłówki `Language` oraz `Plural-Forms`. Aby poprawić tłumaczenie języka, edytuj jego istniejący plik `.po`.
2. Przetłumacz ciągi. Zachowaj w tłumaczeniu symbole zastępcze, takie jak `%1$s`.
3. Uruchom `npm run i18n`. To polecenie zapisuje pliki `.mo`, `.l10n.php` i `.json`, które ładuje WordPress.
4. Zatwierdź plik `.po` razem z wygenerowanymi plikami i otwórz pull request.

Jeśli nie możesz uruchomić `npm`, wystarczy pull request zawierający sam plik `.po`. Wygenerowane pliki można dodać przed scaleniem.

## Generowanie brakujących tłumaczeń

Opiekunowie projektu mogą wygenerować brakujące wpisy za pomocą uwierzytelnionego Codex CLI. To opcjonalne polecenie deweloperskie, którego WordPress nie uruchamia:

```bash
npm run i18n:translate -- --dry-run
npm run i18n:translate
```

Domyślnym modelem jest `gpt-6-luna`. Aby pracować nad jednym językiem i regionem, użyj `npm run i18n:translate -- --locale fr_FR`. Polecenie pobiera najnowsze ciągi źródłowe, uzupełnia brakujące tłumaczenia, a następnie kompiluje pliki `.mo`, `.l10n.php` oraz pliki `.json` dla poszczególnych skryptów. Do Codex wysyłane są wyłącznie publiczne ciągi interfejsu, ich kontekst i istniejące formy, bez treści witryny ani danych użytkowników.

Istniejące, niepuste tłumaczenia nigdy nie są zastępowane. Zakończone partie są zapisywane, więc po przerwaniu można wznowić pracę od brakujących wpisów. Przed zapisaniem sprawdzane są symbole zastępcze, takie jak `%1$s`, znacznik HTML, identyfikatory techniczne oraz wymagane formy liczby mnogiej. Wpisy oznaczone jako niepewne i zmienione formy liczby mnogiej w źródle pozostawia się do sprawdzenia przez tłumacza. Jeśli żądany model jest niedostępny, nie używa się modelu zastępczego.

`npm run i18n:locales` jawnie odświeża listę języków i reguły liczby mnogiej z WordPress/GlotPress. `npm run i18n:coverage` sprawdza, czy wszystkie języki z listy zapisanej w repozytorium są kompletne. Ani kontrola zakresu tłumaczeń, ani standardowe CI nie wywołują AI i nie pobierają danych o językach. Opcje grupowania, współbieżności i odzyskiwania pracy opisano w pliku README repozytorium.

## Ciągi w kodzie przeznaczone do tłumaczenia

- PHP: użyj funkcji WordPress z domeną tekstową `blockstudio`, na przykład `__( 'Invalid block.', 'blockstudio' )`.
- JavaScript: zaimportuj `__` z `@/utils/__` i przekaż literał tekstowy, na przykład `__( 'Add row' )`. Ciągu złożonego w czasie działania nie można przetłumaczyć, dlatego użyj jednego literału tekstowego dla każdego wariantu.
- Nowy pakiet skryptu z ciągami przeznaczonymi do tłumaczenia wymaga wpisu w `scripts/i18n.ts` i wywołania `wp_set_script_translations()` z tym samym uchwytem i `Translations::script_path()`.

Po zmianie ciągów uruchom `npm run i18n`. Aktualizuje on `languages/blockstudio.pot` i każdy plik `.po`. Nowe ciągi pozostają po angielsku, dopóki tłumacz lub `npm run i18n:translate` ich nie uzupełni. CI uruchamia `npm run i18n:check` i `npm run i18n:coverage`, które odrzucają nieaktualne skompilowane pliki, problemy z ekstrakcją lub niepełne pokrycie lokalizacji. Generowanie nadal jest jawnym działaniem opiekuna projektu.