Dịch trang web Nuxt và Vue của bạn bằng Intlayer | Quốc tế hóa (i18n)

Xem Application Template trên GitHub.

Mục lục

Intlayer là gì?

Intlayer là một thư viện quốc tế hóa (i18n) mã nguồn mở sáng tạo, được thiết kế để đơn giản hóa việc hỗ trợ đa ngôn ngữ trong các ứng dụng web hiện đại.

Với Intlayer, bạn có thể:

• Dễ dàng quản lý bản dịch bằng cách sử dụng các từ điển khai báo ở cấp độ component.
• Định vị động metadata, các route và nội dung.
• Đảm bảo hỗ trợ TypeScript với các kiểu tự động tạo, cải thiện tính năng tự động hoàn thành và phát hiện lỗi.
• Tận hưởng các tính năng nâng cao, như phát hiện và chuyển đổi locale động.

Hướng dẫn từng bước để thiết lập Intlayer trong ứng dụng Nuxt

Bước 1: Cài đặt các phụ thuộc

Cài đặt các gói cần thiết bằng npm:

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

• intlayer

  Gói cốt lõi cung cấp các công cụ quốc tế hóa cho quản lý cấu hình, dịch thuật, khai báo nội dung, biên dịch lại, và các lệnh CLI.

• vue-intlayer Gói tích hợp Intlayer với ứng dụng Vue. Nó cung cấp các composables cho các component Vue.

• nuxt-intlayer Module Nuxt tích hợp Intlayer với các ứng dụng Nuxt. Nó cung cấp thiết lập tự động, middleware để phát hiện locale, quản lý cookie, và chuyển hướng URL.

Bước 2: Cấu hình dự án của bạn

Tạo một file cấu hình để cấu hình các ngôn ngữ cho ứng dụng của bạn:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Các locale khác của bạn    ],    defaultLocale: Locales.ENGLISH,  },  content: {    contentDir: ["."], // Vì mặc định Intlayer sẽ theo dõi các file khai báo nội dung từ thư mục `./src`  },};export default config;

Thông qua tệp cấu hình này, bạn có thể thiết lập URL theo ngôn ngữ, chuyển hướng middleware, tên cookie, vị trí và phần mở rộng của khai báo nội dung, tắt các log của Intlayer trên console, và nhiều hơn nữa. Để xem danh sách đầy đủ các tham số có sẵn, hãy tham khảo tài liệu cấu hình.

Bước 3: Tích hợp Intlayer vào Cấu hình Nuxt của bạn

Thêm module intlayer vào cấu hình Nuxt của bạn:

import { defineNuxtConfig } from "nuxt/config";export default defineNuxtConfig({  // ... Cấu hình Nuxt hiện có của bạn  modules: ["nuxt-intlayer"],});

Module nuxt-intlayer tự động xử lý việc tích hợp Intlayer với Nuxt. Nó thiết lập việc xây dựng khai báo nội dung, theo dõi các tệp trong chế độ phát triển, cung cấp middleware để phát hiện locale, và quản lý định tuyến theo locale.

Bước 4: Khai báo Nội dung của Bạn

Tạo và quản lý các khai báo nội dung để lưu trữ các bản dịch:

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({ en: "Check out ", fr: "Vérifiez ", es: "Compruebe " }),    nuxtIntlayer: t({      en: "Nuxt Intlayer documentation",      fr: "Documentation de Nuxt Intlayer",      es: "Documentación de Nuxt Intlayer",    }),    learnMore: t({      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({      en: "Nuxt Documentation",      fr: "Documentation Nuxt",      es: "Documentación de Nuxt",    }),    readTheDocs: t({      en: "Click on the Nuxt logo to learn more",      // Nhấp vào logo Nuxt để tìm hiểu thêm      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;

Các khai báo nội dung của bạn có thể được định nghĩa ở bất kỳ đâu trong ứng dụng của bạn miễn là chúng được bao gồm trong thư mục contentDir (mặc định là ./src). Và phù hợp với phần mở rộng tệp khai báo nội dung (mặc định là .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Để biết thêm chi tiết, hãy tham khảo tài liệu khai báo nội dung.

Bước 5: Sử dụng Intlayer trong Mã của Bạn

Truy cập các từ điển nội dung của bạn trong toàn bộ ứng dụng Nuxt bằng cách sử dụng 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>

Truy cập Nội dung trong Intlayer

Intlayer cung cấp các API khác nhau để truy cập nội dung của bạn:

• Cú pháp dựa trên Component (được khuyến nghị): Sử dụng cú pháp <myContent />, hoặc <Component :is="myContent" /> để hiển thị nội dung như một Node của Intlayer. Điều này tích hợp liền mạch với Visual Editor và CMS.

• Cú pháp dựa trên chuỗi: Sử dụng {{ myContent }} để hiển thị nội dung dưới dạng văn bản thuần, không hỗ trợ Visual Editor.

• Cú pháp HTML thô: Sử dụng <div v-html="myContent" /> để hiển thị nội dung dưới dạng HTML thô, không hỗ trợ Visual Editor.

• Cú pháp phân rã (Destructuration): useIntlayer composable trả về một Proxy chứa nội dung. Proxy này có thể được destructure để truy cập nội dung trong khi vẫn giữ được tính reactive.
• Sử dụng const content = useIntlayer("myContent"); và {{ content.myContent }} / <content.myContent />.
• Hoặc sử dụng const { myContent } = useIntlayer("myContent"); và {{ myContent}} / <myContent/> để destructure nội dung.

(Tùy chọn) Bước 6: Thay đổi ngôn ngữ của nội dung

Để thay đổi ngôn ngữ của nội dung, bạn có thể sử dụng hàm setLocale được cung cấp bởi composable useLocale. Hàm này cho phép bạn thiết lập locale của ứng dụng và cập nhật nội dung tương ứng.

Tạo một component để chuyển đổi giữa các ngôn ngữ:

<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";// Lấy thông tin locale và hàm setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Theo dõi locale được chọn với refconst selectedLocale = ref(locale.value);// Cập nhật locale khi lựa chọn thay đổiconst changeLocale = () => setLocale(selectedLocale.value);// Giữ selectedLocale đồng bộ với locale toàn cụcwatch(  () => 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>

Sau đó, sử dụng component này trong các trang hoặc layout của bạn:

<script setup lang="ts">import { useIntlayer } from "vue-intlayer";import LocaleSwitcher from "~/components/LocaleSwitcher.vue";const content = useIntlayer("app"); // Tạo file khai báo intlayer liên quan</script><template>  <div>    <header>      <LocaleSwitcher />    </header>    <main>      <NuxtPage />    </main>  </div></template>

(Tùy chọn) Bước 7: Thêm định tuyến đa ngôn ngữ vào ứng dụng của bạn

Nuxt tự động xử lý định tuyến đa ngôn ngữ khi sử dụng module nuxt-intlayer. Điều này tạo ra các route cho mỗi ngôn ngữ một cách tự động dựa trên cấu trúc thư mục pages của bạn.

Ví dụ:

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

Để tạo một trang đa ngôn ngữ, chỉ cần tạo các file Vue trong thư mục 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>

Module nuxt-intlayer sẽ tự động:

• Phát hiện ngôn ngữ ưu tiên của người dùng
• Xử lý chuyển đổi ngôn ngữ qua URL
• Đặt thuộc tính <html lang=""> phù hợp
• Quản lý cookie ngôn ngữ
• Chuyển hướng người dùng đến URL đa ngôn ngữ phù hợp

(Tùy chọn) Bước 8: Tạo thành phần Liên kết Đa ngôn ngữ

Để đảm bảo điều hướng trong ứng dụng của bạn tôn trọng ngôn ngữ hiện tại, bạn có thể tạo một thành phần tùy chỉnh LocalizedLink. Thành phần này tự động thêm tiền tố ngôn ngữ hiện tại vào các URL nội bộ.

<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();// Kiểm tra xem liên kết có phải là liên kết ngoài khôngconst isExternalLink = computed(() => /^https?:\/\//.test(props.to || ""));// Tạo href có địa phương hóa cho các liên kết nội bộconst localizedHref = computed(() =>  isExternalLink.value ? props.to : getLocalizedUrl(props.to, locale.value));</script>

Sau đó sử dụng component này trong toàn bộ ứng dụng của bạn:

<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>

(Tùy chọn) Bước 9: Xử lý Metadata và SEO

Nuxt cung cấp các khả năng SEO tuyệt vời. Bạn có thể sử dụng Intlayer để xử lý metadata được bản địa hóa:

<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>

Tạo khai báo nội dung tương ứng:

import { t, type Dictionary } from "intlayer";import type { useSeoMeta } from "nuxt/app";const aboutMetaContent = {  key: "about-meta",  content: {    title: t({      vi: "Về Chúng Tôi - Công Ty Tôi",      en: "About Us - My Company",      fr: "À Propos - Ma Société",      es: "Acerca de Nosotros - Mi Empresa",    }),    description: t({      vi: "Tìm hiểu thêm về công ty và sứ mệnh của chúng tôi",      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;

Cấu hình TypeScript

Intlayer sử dụng module augmentation để tận dụng lợi ích của TypeScript và làm cho codebase của bạn mạnh mẽ hơn.

Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu được tạo tự động.

{  // ... Các cấu hình TypeScript hiện có của bạn  "include": [    // ... Các cấu hình TypeScript hiện có của bạn    ".intlayer/**/*.ts", // Bao gồm các kiểu được tạo tự động  ],}

Cấu hình Git

Khuyến nghị bạn nên bỏ qua các file được tạo bởi Intlayer. Điều này giúp bạn tránh việc commit chúng vào kho Git của mình.

Để làm điều này, bạn có thể thêm các hướng dẫn sau vào file .gitignore của bạn:

# Bỏ qua các file được tạo bởi Intlayer.intlayer

Tiện ích mở rộng VS Code

Để cải thiện trải nghiệm phát triển với Intlayer, bạn có thể cài đặt Tiện ích mở rộng Intlayer cho VS Code chính thức.

Cài đặt từ VS Code Marketplace

Tiện ích mở rộng này cung cấp:

• Tự động hoàn thành cho các khóa dịch.
• Phát hiện lỗi thời gian thực cho các bản dịch còn thiếu.
• Xem trước nội dung dịch ngay trong dòng.
• Hành động nhanh để dễ dàng tạo và cập nhật các bản dịch.

Để biết thêm chi tiết về cách sử dụng tiện ích mở rộng, hãy tham khảo Tài liệu Tiện ích mở rộng Intlayer cho VS Code.

Tiến xa hơn

Để tiến xa hơn, bạn có thể triển khai trình soạn thảo trực quan hoặc tách nội dung của bạn ra ngoài bằng cách sử dụng CMS.