Wnioskowanie typów zależne od lokalizacji
Zapewniaj wszystkim lokalizacjom taką samą strukturę kluczy
Wnioskowanie typów zależne od lokalizacji to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Wnioskowanie typów zależne od locale
Aplikacja obsługuje wiele locale (en, tr, de...). Potrzebny jest typ, który zgłasza błąd, gdy któremukolwiek locale brakuje kluczy obecnych w bazowym locale, aby tłumaczenia nigdy nie rozeszły się po cichu.
Bazowe locale
Należy wybrać jedno locale (zwykle en) jako kanoniczną strukturę kluczy. Każde inne locale musi mieć taką samą strukturę.
const en = {
greeting: "Hello",
cart: { empty: "Empty", checkout: "Checkout" },
} as const;
type Base = typeof en;Ograniczanie pozostałych locale
Każde dodatkowe locale należy typować jako strukturę bazową. Brakujący klucz staje się wtedy błędem kompilacji w pliku tego locale.
const tr: Base = {
greeting: "Merhaba",
cart: { empty: "Bo\u015f", checkout: "\u00d6deme" },
};
// Omitting cart.checkout -> Error: property missingWykrywanie dodatkowych kluczy
Użycie typu bazowego jako adnotacji sygnalizuje również nieznane klucze, które istnieją w locale, ale nie występują w bazowym locale, wykrywając pozostałe lub błędnie zapisane wpisy.
const de: Base = {
greeting: "Hallo",
cart: { empty: "Leer", checkout: "Kasse" },
extra: "oops", // Error: not in Base
};Helper do definiowania locale
Generyczny helper wymusza odpowiednią strukturę, zachowując jednocześnie każdą wartość i zapewniając przejrzyste miejsce definicji dla poszczególnych locale.
function defineLocale<T extends Base>(loc: T): T {
return loc;
}
const fr = defineLocale({
greeting: "Bonjour",
cart: { empty: "Vide", checkout: "Paiement" },
});Rejestr wszystkich locale
Locale należy zebrać w rekordzie. Ograniczenie każdej wartości do Base gwarantuje jednolitą strukturę w całej aplikacji.
const locales: Record<string, Base> = { en, tr, de: fr };
// every entry must have the full Base key structureRówność na poziomie typów (głęboka)
Aby uzyskać bardziej rygorystyczne gwarancje, można zbudować typ SameKeys, który głęboko porównuje struktury kluczy i zwraca typ błędu, gdy się one różnią. Zapewnia to więcej niż zwykła adnotacja.
type SameKeys<A, B> =
keyof A extends keyof B
? keyof B extends keyof A ? true : false
: false;Jednorazowe wyprowadzanie kluczy
Ponieważ wszystkie locale współdzielą Base, typ ścieżek kluczy (z poprzedniej lekcji) jest obliczany raz na podstawie Base i ponownie używany dla każdego locale, dzięki czemu typowanie t jest niezależne od locale.
type Key = LeafPaths<Base>;
// same valid keys regardless of active localeWybór locale w czasie działania
W czasie działania rejestr jest indeksowany za pomocą aktywnego locale. System typów zagwarantował już, że każde locale ma te same klucze, więc wyszukiwanie jest bezpieczne.
function translate(locale: keyof typeof locales, key: Key): string {
return getPath(locales[locale], key);
}Wykrywanie brakujących kluczy we wszystkich locale
Jeśli nie można bezpośrednio opisać typem każdego pliku (np. w przypadku importów JSON), kontrola typów podczas budowania porównuje każde zaimportowane locale z Base i ujawnia typ różnicy zawierający listę brakujących kluczy.
type Missing<L> = Exclude<keyof Base, keyof L>;
type TrMissing = Missing<typeof tr>; // never if completeDlaczego to ma znaczenie
i18n bez typów rozchodzi się: klucz dodany do en zostaje pominięty w de, przez co do użytkowników trafia pusty tekst lub tekst angielski. Ograniczenie każdego locale do wspólnej struktury bazowej zamienia takie pominięcie w błąd kompilacji, zapewniając kompletność i spójność wszystkich locale.
Szybki test
Proszę sprawdzić, czy rozumieją Państwo wnioskowanie typów zależne od locale.
Podsumowanie
Wybrane zostało bazowe locale jako kanoniczna struktura, a każde inne locale zostało do niego ograniczone, dzięki czemu brakujące lub dodatkowe klucze uniemożliwiają kompilację. Helper defineLocale i ograniczony rejestr utrzymują identyczną strukturę wszystkich locale, a ścieżki kluczy są wyprowadzane raz na podstawie bazowego locale.
Często zadawane pytania
Czy lekcja „Wnioskowanie typów zależne od lokalizacji” jest bezpłatna?
Tak — pełny tekst „Wnioskowanie typów zależne od lokalizacji” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Wnioskowanie typów zależne od lokalizacji”?
Zapewniaj wszystkim lokalizacjom taką samą strukturę kluczy Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?
Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.
Ile czasu zajmuje lekcja „Wnioskowanie typów zależne od lokalizacji”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?
Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Typowanie kluczy tłumaczeń
- Bezpieczeństwo typów interpolacji
- Liczba mnoga z typami
- Wnioskowanie typów zależne od lokalizacji