0Pricing
TypeScript Academy · Lekcja

Typowanie kluczy tłumaczeń

Wyprowadzaj unię poprawnych kluczy z plików komunikatów

Typowanie kluczy tłumaczeń to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 1 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.

Wyprowadzanie poprawnych kluczy tłumaczeń

W konfiguracji i18n bezpiecznej typowo zbiór poprawnych kluczy tłumaczeń jest wyprowadzany z obiektu messages. Literówka, taka jak t("greetng"), staje się błędem kompilacji, a nie błędem braku tekstu ujawniającym się w czasie działania.

Obiekt messages

Należy zacząć od zwykłego obiektu zawierającego komunikaty. Jest on pojedynczym źródłem prawdy zarówno dla wartości, jak i typu kluczy.

const messages = {
  greeting: "Hello",
  farewell: "Goodbye",
  cart: {
    empty: "Your cart is empty",
    checkout: "Proceed to checkout",
  },
} as const;

Klucze najwyższego poziomu za pomocą keyof

W przypadku płaskiego obiektu keyof typeof zwraca unię jego kluczy.

type TopKeys = keyof typeof messages;
// "greeting" | "farewell" | "cart"

Problem z zagnieżdżeniem

Rzeczywiste katalogi komunikatów są zagnieżdżone. Chcemy uzyskać ścieżki rozdzielane kropkami, takie jak "cart.empty", a nie tylko klucze najwyższego poziomu. Potrzebujemy typu rekurencyjnego, który przejdzie przez obiekt.

Rekurencyjny typ ścieżki

Typ warunkowy połączony z typem mapowanym buduje ścieżki rozdzielane kropkami, rekurencyjnie przechodząc do zagnieżdżonych obiektów i dodając przedrostki do kluczy. Przedrostek używa typu literału szablonowego, zapisywanego w prawdziwym kodzie za pomocą backticków jako [backtick]${K}.${Paths<T[K]>}[backtick]. Poniżej pokazujemy go jako JoinPath(K, child), aby zachować przejrzystość listingu.

type JoinPath<K extends string, Rest extends string> = K + "." + Rest;
// (Real TS uses a template literal type:
//   the K dot Rest pattern delimited by backticks.)

type Paths<T> = {
  [K in keyof T & string]: T[K] extends string
    ? K
    : K | (T[K] extends object
        ? JoinPath<K, Paths<T[K]>>
        : never);
}[keyof T & string];

Zastosowanie typu

Przekazanie typu messages do Paths daje każdą poprawną ścieżkę rozdzielaną kropkami.

type MsgKey = Paths<typeof messages>;
// "greeting" | "farewell" | "cart" | "cart.empty" | "cart.checkout"

Tylko klucze liści

Często potrzebne są wyłącznie ścieżki liści (rzeczywiste ciągi znaków), z wykluczeniem obiektów pośrednich. Należy zmodyfikować rekurencję tak, aby pomijała węzły, które nie są ciągami znaków. Przedrostek K-kropka-dziecko również korzysta z typu literału szablonowego (w prawdziwym kodzie ograniczonego backtickami); tutaj pokazujemy go jako JoinPath.

type LeafPaths<T> = T extends string
  ? ""
  : {
      [K in keyof T & string]: T[K] extends string
        ? K
        : JoinPath<K, LeafPaths<T[K]>>;
    }[keyof T & string];
// "greeting" | "farewell" | "cart.empty" | "cart.checkout"

Funkcja t z typami

Należy ograniczyć parametr funkcji tłumaczącej do wyprowadzonej unii kluczy, aby kompilowały się wyłącznie poprawne klucze.

declare function t(key: LeafPaths<typeof messages>): string;

t("cart.empty");   // ok
t("cart.missing"); // Error: not a valid key

Wyznaczanie typu wartości

Można pójść o krok dalej i wywnioskować typ wartości dla danej ścieżki, co jest przydatne, gdy komunikaty zawierają elementy inne niż ciągi znaków. Warunkowy typ indeksujący ścieżkę przechodzi przez kropki. Dzieli ścieżkę za pomocą wzorca literału szablonowego, który w prawdziwym kodzie zapisuje się z użyciem backticków jako kształt Head kropka Rest z infer. Poniżej oznaczamy ten podział jako SplitHead/SplitRest.

// Conceptually: split "cart.empty" into Head="cart", Rest="empty"
// using a template literal pattern with infer.

type ValueAt<T, P extends string> =
  P extends SplitHead<infer Head, infer Rest>
    ? Head extends keyof T ? ValueAt<T[Head], Rest> : never
    : P extends keyof T ? T[P] : never;

Dlaczego as const ma znaczenie

Bez as const wartości tekstowe rozszerzają się do typu string i tracą informacje literałowe potrzebne później (na przykład do wyodrębniania symboli zastępczych). Katalogi należy zawsze deklarować jako const.

Dlaczego ma to znaczenie

Wyprowadzanie kluczy z katalogu oznacza, że dodanie, zmiana nazwy lub usunięcie komunikatu natychmiast aktualizuje dozwolony typ klucza w całym kodzie. Nie trzeba utrzymywać centralnego enuma ani nieaktualnych stałych tekstowych.

Szybkie sprawdzenie

Sprawdź swoje rozumienie typowania kluczy tłumaczeń.

Podsumowanie

Wyprowadzili Państwo unię poprawnych kluczy z obiektu messages, używając keyof oraz rekurencyjnego typu ścieżki opartego na literałach szablonowych. Warianty ograniczone do liści wykluczają obiekty pośrednie, typowana funkcja t odrzuca niepoprawne klucze, a as const zachowuje informacje literałowe potrzebne mechanizmowi typów.

Często zadawane pytania

Czy lekcja „Typowanie kluczy tłumaczeń” jest bezpłatna?

Tak — pełny tekst „Typowanie kluczy tłumaczeń” 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 „Typowanie kluczy tłumaczeń”?

Wyprowadzaj unię poprawnych kluczy z plików komunikatów Ć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 1 z 4.

Ile czasu zajmuje lekcja „Typowanie kluczy tłumaczeń”?

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

  1. Typowanie kluczy tłumaczeń
  2. Bezpieczeństwo typów interpolacji
  3. Liczba mnoga z typami
  4. Wnioskowanie typów zależne od lokalizacji
← Powrót do TypeScript Academy