Dịch trang web Astro của bạn với Intlayer

Mục lục

Tại sao Intlayer thay thế các lựa chọn thay thế?

So với các giải pháp chính như astro-i18n hay i18next, Intlayer là giải pháp đi kèm với các tính năng tối ưu hóa tích hợp như:

Hướng dẫn từng bước để cấu hình Intlayer trong Astro

Xem mẫu ứng dụng trên GitHub.

1. 1

   Cài đặt các phụ thuộc

   Cài đặt các gói cần thiết bằng trình quản lý gói ưa thích của bạn:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npx intlayer init --interactive
   

   flag --interactive là tuỳ chọn. Sử dụng intlayer-cli init nếu bạn là một agent AI.

   Lệnh này sẽ phát hiện môi trường của bạn và cài đặt các gói cần thiết. Ví dụ:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install intlayer astro-intlayer
   

   • intlayer Gói cốt lõi cung cấp các công cụ i18n để quản lý cấu hình, bản dịch, khai báo nội dung, chuyển mã và các lệnh CLI.

   • astro-intlayer Bao gồm plugin tích hợp Astro để tích hợp Intlayer với Vite bundler, một middleware phân giải ngôn ngữ của mỗi yêu cầu vào Astro.locals.intlayer, và các hook useIntlayer / useDictionary / useLocale. Cùng một đường dẫn import sẽ phân giải thành triển khai máy chủ trong frontmatter .astro của bạn và thành triển khai máy khách (được hỗ trợ bởi vanilla-intlayer) trong các khối <script>.

2. 2

   Cấu hình dự án của bạn

   Kiến trúc

   Trong kiến trúc này, tích hợp intlayer() được đăng ký trong astro.config.ts sẽ xây dựng các từ điển của bạn và thêm một middleware giúp xử lý locale của mỗi yêu cầu và hiển thị nó trên Astro.locals.intlayer. Các trang nằm dưới phân đoạn rest src/pages/[...locale]/, do đó locale mặc định được phân phối mà không có tiền tố và mọi locale khác đều có URL riêng biệt. Các tệp .astro đọc nội dung bằng các hook useIntlayer / useLocale của astro-intlayer, và các khai báo nội dung được đặt cùng với các component của bạn trong src/.

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Cấu hình

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

   intlayer.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         Locales.VIETNAMESE,
         // Các ngôn ngữ khác của bạn
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

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

   tài liệu cấu hình
3. 3

   Tích hợp Intlayer vào cấu hình Astro của bạn

   Thêm plugin intlayer vào cấu hình Astro của bạn.

   astro.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer()],
   });
   

   Plugin tích hợp intlayer() được sử dụng để tích hợp Intlayer với Astro. Nó đảm bảo việc tạo các file khai báo nội dung và theo dõi chúng trong chế độ phát triển. Nó xác định các biến môi trường Intlayer bên trong ứng dụng Astro và cung cấp các alias để tối ưu hóa hiệu suất.

4. 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 của bạn để lưu trữ các bản dịch:

   src/app.content.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         vi: "Xin chào thế giới",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

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

   Để biết thêm thông tin, hãy xem tài liệu khai báo nội dung.

   tài liệu khai báo nội dung
5. 5

   Sử dụng nội dung trong Astro

   Sử dụng từ điển của bạn trong các tệp .astro với các hook được xuất bởi astro-intlayer. Chúng chia sẻ chữ ký của react-intlayer: useIntlayer("key") trả về nội dung của từ điển và useLocale() trả về ngôn ngữ hiện tại mà không cần truyền tham số.

   Ngôn ngữ đến từ middleware astro-intlayer, mà tích hợp tự động đăng ký trước src/middleware.ts của riêng bạn. Nó phân giải ngôn ngữ cho mỗi yêu cầu, từ tiền tố URL, sau đó đến ngôn ngữ được lưu trữ bởi máy khách (cookie hoặc tiêu đề), sau đó đến Accept-Language, và lưu trữ trong Astro.locals.intlayer. Các trang được kết xuất trước chỉ sử dụng URL vì chúng được kết xuất một lần cho mọi khách truy cập.

   Bạn cũng nên thêm siêu dữ liệu SEO như hreflang và liên kết chuẩn (canonical) vào mỗi trang và bao gồm bộ chuyển đổi ngôn ngữ để cho phép người dùng thay đổi ngôn ngữ.

   src/pages/index.astro

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // Ngôn ngữ được phân giải bởi middleware (ví dụ /vi/about -> 'vi')
   const { locale } = useLocale();
   
   // Nội dung của từ điển 'app' cho ngôn ngữ đó
   const { title } = useIntlayer("app");
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Canonical link: Tells search engines which is the primary version of this page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Tell Google about all localized versions -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback for users in unmatched languages -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <header>
         <LocaleSwitcher />
       </header>
       <main>
         <h1>{title}</h1>
       </main>
     </body>
   </html>
   

   Astro.locals.intlayer cũng hiển thị locale, defaultLocale và availableLocales cho middleware và điểm cuối của riêng bạn. Truyền ngôn ngữ hoặc bộ chọn làm đối số thứ hai (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })) để ghi đè ngôn ngữ yêu cầu cho một lệnh gọi.

6. 6

   Định tuyến bản địa hóa

   Tạo các đoạn route động (ví dụ: src/pages/[locale]/index.astro) để phục vụ các trang bản địa hóa:

   src/pages/[locale]/index.astro

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   Tích hợp Astro thêm middleware Vite giúp định tuyến nhận biết ngôn ngữ và định nghĩa môi trường trong quá trình phát triển. Bạn cũng có thể sử dụng logic của riêng mình hoặc các công cụ intlayer như getLocalizedUrl để liên kết giữa các ngôn ngữ.

7. 7

   Thêm bộ chuyển đổi ngôn ngữ

   Để cho phép người dùng chuyển đổi giữa các ngôn ngữ, bạn có thể tạo một thành phần LocaleSwitcher. Thành phần này sẽ hiển thị danh sách tất cả các ngôn ngữ được hỗ trợ và liên kết đến cùng một trang trong mỗi ngôn ngữ.

   src/components/LocaleSwitcher.astro

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // Trong trình duyệt, cùng một import sẽ phân giải thành triển khai máy khách
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Lưu lựa chọn vào cookie ngôn ngữ, sau đó điều hướng đến URL đã bản địa hóa
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   Lưu ý về tính bền vững: setLocale từ useLocale phía client lưu tùy chọn ngôn ngữ của người dùng vào cookie. Điều này cho phép Intlayer ghi nhớ lựa chọn và tự động chuyển hướng người dùng đến ngôn ngữ ưa thích của họ trong các lần truy cập sau: các trang được render theo yêu cầu (một adapter với output: 'server' hoặc prerender = false) được chuyển hướng bởi middleware Intlayer trước khi bất kỳ mã HTML nào được gửi đi, trong khi các trang được render sẵn, được phân phối dưới dạng tệp tĩnh, được chuyển hướng bởi một đoạn script nhỏ mà tích hợp đưa vào mỗi trang. Đặt routing.enableProxy thành false để tắt cả hai. Trong astro dev, cookie bị bỏ qua như một nguồn chuyển hướng trừ khi routing.enableProxy được đặt thành true, do đó cookie cũ không thể chiếm quyền kiểm soát các trang bạn đang phát triển.

   Khả năng tương thích giữa máy chủ và máy khách: astro-intlayer phân giải thành các hook máy chủ trong frontmatter (đọc Astro.locals) và thành các hook máy khách của vanilla-intlayer trong các khối <script> và đảo (islands), với cùng tên và cấu trúc nội dung. setLocale và onChange chỉ hoạt động trên máy khách, hãy gọi installIntlayer() một lần ở đó để khởi tạo bộ lưu trữ máy khách. astro-intlayer/client hiển thị mục nhập máy khách một cách rõ ràng.

8. 8

   Sitemap và Robots.txt

   Intlayer cung cấp các tiện ích để tự động tạo sơ đồ trang web (sitemap) bản địa hóa và file robots.txt của bạn.

   Sitemap

   Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

   The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

   Tạo src/pages/sitemap.xml.ts để tạo sơ đồ trang web bao gồm tất cả các route bản địa hóa của bạn.

   src/pages/sitemap.xml.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   Tạo src/pages/robots.txt.ts để kiểm soát hoạt động thu thập thông tin của các công cụ tìm kiếm.

   src/pages/robots.txt.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 9

   Tiếp tục sử dụng Framework yêu thích của bạn

   Tiếp tục xây dựng ứng dụng của bạn bằng cách sử dụng framework mà bạn chọn.

   Intlayer với React

   Intlayer với Vue

   Intlayer với Svelte

   Intlayer với Solid

   Intlayer với Preact

   Intlayer với Lit
10. 15

    Trích xuất nội dung các thành phần của bạn

    Tùy chọn

    Nếu bạn có một cơ sở mã hiện có, việc chuyển đổi hàng nghìn tệp có thể tốn nhiều thời gian.

    Để đơn giản hóa quy trình này, Intlayer đề xuất một trình biên dịch / trình trích xuất để chuyển đổi các thành phần của bạn và trích xuất nội dung.

    trình biên dịch

    trình trích xuất

    Để thiết lập, bạn có thể thêm phần compiler vào tệp intlayer.config.ts của mình:

    intlayer.config.ts

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Phần còn lại của cấu hình
      compiler: {
        /**
         * Cho biết trình biên dịch có nên được bật hay không.
         */
        enabled: true,
    
        /**
         * Xác định đường dẫn các tệp đầu ra
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Cho biết các thành phần có nên được lưu sau khi chuyển đổi hay không. Bằng cách đó, trình biên dịch có thể được chạy chỉ một lần để chuyển đổi ứng dụng, sau đó có thể được gỡ bỏ.
         */
        saveComponents: false,
    
        /**
         * Tiền tố khóa từ điển
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Lệnh trích xuấtTrình biên dịch Babel

    Chạy trình trích xuất để chuyển đổi các thành phần và trích xuất nội dung

    bash

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    npx intlayer extract
    

    Build ứng dụng của bạn để chuyển đổi các thành phần và trích xuất nội dung

    bash

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    npm run build # Hoặc npm run dev
    

Cấu hình TypeScript

Intlayer sử dụng cơ chế mở rộng module (module augmentation) để tận dụng TypeScript, làm cho cơ sở mã 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 dữ liệu được tạo tự động.

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

Cấu hình Git

Khuyên bạn nên bỏ qua các file được tạo bởi Intlayer. Điều này ngăn chúng được commit vào kho lưu trữ Git của bạn.

Để làm điều đó, hãy 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 của bạn với Intlayer, bạn có thể cài đặt tiện ích mở rộng Intlayer chính thức cho VS Code.

Tiện ích này sẽ 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 trực tiếp nội dung đã dịch.
• Các hành động nhanh để tạo và cập nhật bản dịch dễ dàng.

Để biết thêm thông tin về cách sử dụng tiện ích này, hãy xem tài liệu tiện ích VS Code.

Tìm hiểu sâu hơn

Nếu bạn muốn tìm hiểu thêm, bạn cũng có thể triển khai Visual Editor hoặc sử dụng CMS để quản lý nội dung bên ngoài.

Các Câu Hỏi Thường Gặp