Przetłumacz swoją stronę Nuxt i Vue za pomocą Intlayer | Internacjonalizacja (i18n)

Zobacz Application Template na GitHub.

Spis treści

Czym jest Intlayer?

Intlayer to innowacyjna, open-source'owa biblioteka do internacjonalizacji (i18n), zaprojektowana, aby uprościć obsługę wielojęzyczności we współczesnych aplikacjach webowych.

Dzięki Intlayer możesz:

• Łatwo zarządzać tłumaczeniami za pomocą deklaratywnych słowników na poziomie komponentów.
• Dynamicznie lokalizować metadane, trasy i treści.
• Zapewnić wsparcie dla TypeScript dzięki automatycznie generowanym typom, co poprawia autouzupełnianie i wykrywanie błędów.
• Korzystać z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie lokalizacji.

Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Nuxt

Krok 1: Instalacja zależności

Zainstaluj niezbędne pakiety za pomocą npm:

npm install intlayer vue-intlayernpm install --save-dev nuxt-intlayer

• intlayer

• intlayer

  Podstawowy pakiet, który dostarcza narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilecji oraz poleceń CLI.

• vue-intlayer Pakiet integrujący Intlayer z aplikacją Vue. Zawiera composables dla komponentów Vue.

• nuxt-intlayer Moduł Nuxt integrujący Intlayer z aplikacjami Nuxt. Zapewnia automatyczną konfigurację, middleware do wykrywania lokalizacji, zarządzanie ciasteczkami oraz przekierowania URL.

Krok 2: Konfiguracja Twojego projektu

Utwórz plik konfiguracyjny, aby skonfigurować języki swojej aplikacji:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Twoje inne lokalizacje    ],    defaultLocale: Locales.ENGLISH,  },  content: {    contentDir: ["."], // Domyślnie Intlayer będzie obserwować pliki deklaracji treści z katalogu `./src`  },};export default config;

Za pomocą tego pliku konfiguracyjnego możesz ustawić lokalizowane adresy URL, przekierowania w middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracyjnej.

Krok 3: Zintegruj Intlayer w swojej konfiguracji Nuxt

Dodaj moduł intlayer do swojej konfiguracji Nuxt:

import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Twoja istniejąca konfiguracja Nuxt  modules: ["nuxt-intlayer"],});

Moduł nuxt-intlayer automatycznie obsługuje integrację Intlayer z Nuxt. Konfiguruje budowanie deklaracji treści, monitoruje pliki w trybie deweloperskim, dostarcza middleware do wykrywania lokalizacji oraz zarządza lokalizowanym routingiem.

Krok 4: Zadeklaruj swoją treść

Twórz i zarządzaj deklaracjami treści, aby przechowywać tłumaczenia:

import { t, type Dictionary } from "intlayer";const helloWorldContent = {  key: "helloworld",  content: {    count: t({ en: "count is ", fr: "le compte est ", es: "el recuento es " }),    edit: t({      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",    }),    checkOut: t({      pl: "Sprawdź ",      en: "Check out ",      fr: "Vérifiez ",      es: "Compruebe ",    }),    nuxtIntlayer: t({      pl: "Dokumentacja Nuxt Intlayer",      en: "Nuxt Intlayer documentation",      fr: "Documentation de Nuxt Intlayer",      es: "Documentación de Nuxt Intlayer",    }),    learnMore: t({      pl: "Dowiedz się więcej o Nuxt w ",      en: "Learn more about Nuxt in the ",      fr: "En savoir plus sur Nuxt dans la ",      es: "Aprenda más sobre Nuxt en la ",    }),    nuxtDocs: t({      pl: "Dokumentacja Nuxt",      en: "Nuxt Documentation",      fr: "Documentation Nuxt",      es: "Documentación de Nuxt",    }),    readTheDocs: t({      pl: "Kliknij logo Nuxt, aby dowiedzieć się więcej",      en: "Click on the Nuxt logo to learn more",      pl: "Kliknij na logo Nuxt, aby dowiedzieć się więcej",      fr: "Cliquez sur le logo Nuxt pour en savoir plus",      es: "Haga clic en el logotipo de Nuxt para obtener más información",    }),  },} satisfies Dictionary;export default helloWorldContent;

Twoje deklaracje zawartości mogą być zdefiniowane w dowolnym miejscu w Twojej aplikacji, pod warunkiem, że znajdują się w katalogu contentDir (domyślnie ./src). I pasują do rozszerzenia pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją deklaracji zawartości.

Krok 5: Wykorzystaj Intlayer w swoim kodzie

Uzyskaj dostęp do swoich słowników zawartości w całej aplikacji Nuxt, korzystając z composable useIntlayer:

<script setup lang="ts">import { ref } from "vue";import { useIntlayer } from "vue-intlayer";defineProps({  msg: String,});const {  count,  edit,  checkOut,  nuxtIntlayer,  learnMore,  nuxtDocs,  readTheDocs,} = useIntlayer("helloworld");const countRef = ref(0);</script><template>  <h1>{{ msg }}</h1>  <div class="card">    <button type="button" @click="countRef++">      <count />      {{ countRef }}    </button>    <p v-html="edit"></p>  </div>  <p>    <checkOut />    <a href="https://nuxt.com/docs/getting-started/introduction" target="_blank"      >Nuxt</a    >, <nuxtIntlayer />  </p>  <p>    <learnMore />    <a href="https://nuxt.com" target="_blank"><nuxtDocs /></a>.  </p>  <p class="read-the-docs"><readTheDocs /></p>  <p class="read-the-docs">{{ readTheDocs }}</p></template>

Dostęp do treści w Intlayer

Intlayer oferuje różne API do dostępu do Twoich treści:

• Składnia oparta na komponentach (zalecana): Użyj składni <myContent /> lub <Component :is="myContent" />, aby wyrenderować treść jako węzeł Intlayer. Integruje się to bezproblemowo z Visual Editor oraz CMS.

• Składnia oparta na łańcuchu znaków: Użyj {{ myContent }}, aby wyrenderować treść jako zwykły tekst, bez wsparcia Visual Editor.

• Składnia surowego HTML: Użyj <div v-html="myContent" />, aby wyrenderować treść jako surowy HTML, bez wsparcia Visual Editor.

• Składnia destrukturyzacji: useIntlayer composable zwraca Proxy z zawartością. Ten proxy można zdestrukturyzować, aby uzyskać dostęp do zawartości, zachowując rekatywność.
• Użyj const content = useIntlayer("myContent"); oraz {{ content.myContent }} / <content.myContent />.
• Lub użyj const { myContent } = useIntlayer("myContent"); oraz {{ myContent }} / <myContent/> do zdestrukturyzowania zawartości.

(Opcjonalnie) Krok 6: Zmień język swojej zawartości

Aby zmienić język swojej zawartości, możesz użyć funkcji setLocale dostarczonej przez composable useLocale. Funkcja ta pozwala ustawić lokalizację aplikacji i odpowiednio zaktualizować zawartość.

Utwórz komponent do przełączania między językami:

<template>  <div class="locale-switcher">    <select v-model="selectedLocale" @change="changeLocale">      <option v-for="loc in availableLocales" :key="loc" :value="loc">        {{ getLocaleName(loc) }}      </option>    </select>  </div></template><script setup lang="ts">import { ref, watch } from "vue";import { getLocaleName } from "intlayer";import { useLocale } from "vue-intlayer";// Pobierz informacje o lokalizacji oraz funkcję setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Śledź wybraną lokalizację za pomocą refconst selectedLocale = ref(locale.value);// Aktualizuj lokalizację po zmianie wyboruconst changeLocale = () => setLocale(selectedLocale.value);// Synchronizuj selectedLocale z globalną lokalizacjąwatch(  () => locale.value,  (newLocale) => {    selectedLocale.value = newLocale;  });</script></template><style scoped>.locale-switcher {  margin: 1rem 0;}select {  padding: 0.5rem;  border-radius: 0.25rem;  border: 1px solid #ccc;}</style>

Następnie użyj tego komponentu na swoich stronach lub w layoucie:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";const content = useIntlayer("app"); // Utwórz powiązany plik deklaracji intlayer</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <NuxtPage />    </main>  </div></template>

(Opcjonalny) Krok 7: Dodaj lokalizowane routingi do swojej aplikacji

Nuxt automatycznie obsługuje lokalizowane routingi podczas korzystania z modułu nuxt-intlayer. Tworzy to trasy dla każdego języka automatycznie na podstawie struktury katalogu stron.

Przykład:

pages/├── index.vue          → /, /fr, /es├── about.vue          → /about, /fr/about, /es/about└── contact/    └── index.vue      → /contact, /fr/contact, /es/contact

Aby utworzyć lokalizowaną stronę, po prostu stwórz swoje pliki Vue w katalogu pages/:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";const content = useIntlayer("about");</script><template>  <div>    <h1>{{ content.title }}</h1>    <p>{{ content.description }}</p>  </div></template>

Moduł nuxt-intlayer automatycznie:

• Wykrywa preferowany język użytkownika
• Obsługuje przełączanie języka przez URL
• Ustawia odpowiedni atrybut <html lang="">
• Zarządza ciasteczkami językowymi
• Przekierowuje użytkowników na odpowiedni zlokalizowany URL

(Opcjonalny) Krok 8: Tworzenie komponentu Lokalizowanego Linku

Aby zapewnić, że nawigacja w Twojej aplikacji respektuje aktualny język, możesz stworzyć niestandardowy komponent LocalizedLink. Komponent ten automatycznie dodaje prefiks języka do wewnętrznych adresów URL.

<template>  <NuxtLink :to="localizedHref" v-bind="$attrs">    <slot />  </NuxtLink></template><script setup lang="ts">import { computed } from "vue";import { getLocalizedUrl } from "intlayer";import { useLocale } from "vue-intlayer";const props = defineProps({  to: {    type: String,    required: true,  },});const { locale } = useLocale();// Sprawdź, czy link jest zewnętrznyconst isExternalLink = computed(() => /^https?:\/\//.test(props.to || ""));// Utwórz zlokalizowany href dla linków wewnętrznychconst localizedHref = computed(() =>  isExternalLink.value ? props.to : getLocalizedUrl(props.to, locale.value));</script>

Następnie użyj tego komponentu w całej aplikacji:

<template>  <div>    <LocalizedLink to="/about">      {{ content.aboutLink }}    </LocalizedLink>    <LocalizedLink to="/contact">      {{ content.contactLink }}    </LocalizedLink>  </div></template><script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocalizedLink from "~/components/LocalizedLink.vue";const content = useIntlayer("home");</script>

(Opcjonalny) Krok 9: Obsługa metadanych i SEO

Nuxt oferuje doskonałe możliwości SEO. Możesz użyć Intlayer do obsługi zlokalizowanych metadanych:

<script setup lang="ts">import { useSeoMeta } from "nuxt/app";import { getIntlayer } from "intlayer";import { useLocale } from "vue-intlayer";const { locale } = useLocale();const content = getIntlayer("about-meta", locale.value);useSeoMeta({  title: content.title,  description: content.description,});</script><template>  <div>    <h1>{{ content.pageTitle }}</h1>    <p>{{ content.pageContent }}</p>  </div></template>

Utwórz odpowiadającą deklarację zawartości:

import { t, type Dictionary } from "intlayer";import type { useSeoMeta } from "nuxt/app";const aboutMetaContent = {  key: "about-meta",  content: {    title: t({      pl: "O nas - Moja Firma",      en: "About Us - My Company",      fr: "À Propos - Ma Société",      es: "Acerca de Nosotros - Mi Empresa",    }),    description: t({      pl: "Dowiedz się więcej o naszej firmie i naszej misji",      en: "Learn more about our company and our mission",      fr: "En savoir plus sur notre société et notre mission",      es: "Conozca más sobre nuestra empresa y nuestra misión",    }),  },} satisfies Dictionary<Parameters<typeof useSeoMeta>[0]>;export default aboutMetaContent;

Konfiguracja TypeScript

Intlayer wykorzystuje rozszerzenia modułów (module augmentation), aby korzystać z zalet TypeScript i uczynić Twoją bazę kodu bardziej solidną.

Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

{  // ... Twoje istniejące konfiguracje TypeScript  "include": [    // ... Twoje istniejące konfiguracje TypeScript    ".intlayer/**/*.ts", // Dołącz automatycznie generowane typy  ],}

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich commitowania do repozytorium Git.

Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby poprawić doświadczenie programistyczne z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z VS Code Marketplace

To rozszerzenie oferuje:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podglądy w linii przetłumaczonej zawartości.
• Szybkie akcje umożliwiające łatwe tworzenie i aktualizowanie tłumaczeń.

Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer VS Code.

Idź dalej

Aby pójść dalej, możesz zaimplementować edytor wizualny lub zewnętrznie zarządzać swoją zawartością za pomocą CMS.