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

Table of Contents

Gói này đang trong quá trình phát triển. Xem vấn đề để biết thêm thông tin. Thể hiện sự quan tâm của bạn đến Intlayer cho Solid bằng cách thích vấn đề này

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ư @solid-primitives/i18n hoặc 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ài Đặt Intlayer trong Ứng Dụng Vite và Solid

Mục Lục

1. 1

   Cài Đặt Các Phụ Thuộc

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

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer init

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

   • solid-intlayer
     Gói tích hợp Intlayer với ứng dụng Solid. Nó cung cấp các context provider và hook cho việc quốc tế hóa trong Solid.

   • vite-intlayer
     Bao gồm plugin Vite để tích hợp Intlayer với trình đóng gói Vite, cũng như middleware để phát hiện locale ưu tiên của người dùng, quản lý cookie, và xử lý chuyển hướng URL.

2. 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:

   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,
         // Các locale khác của bạn
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Thông qua tệp cấu hình này, bạn có thể thiết lập các URL địa phương 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 của bạn, 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.

3. 3

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

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

   vite.config.ts

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { defineConfig } from "vite";
   import react from "@vitejs/plugin-react-swc";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [react(), intlayer()],
   });

   Plugin intlayer() của Vite được sử dụng để tích hợp Intlayer với Vite. Nó đảm bảo việc xây dựng các file khai báo nội dung và giám sát chúng trong chế độ phát triển. Nó định nghĩa các biến môi trường Intlayer trong ứng dụng Vite. Ngoài ra, nó còn cung cấp các bí danh để tối ưu 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 để lưu trữ 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";
   
   const appContent = {
     key: "app",
     content: {},
   } satisfies Dictionary;
   
   export default appContent;

   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 đưa vào thư mục contentDir (mặc định là ./src). Và phải phù hợp với phần mở rộng 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 chi tiết, hãy tham khảo tài liệu khai báo nội dung.

5. 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:

   src/App.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => {  const [count, setCount] = createSignal(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />        </a>        <a href="https://www.solidjs.com/" target="_blank">          <img            src={solidLogo}            class="logo solid"            alt={content.solidLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div class="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count({ count: count() })}        </button>        <p>{content.edit}</p>      </div>      <p class="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: Component = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

   Trong Solid, useIntlayer trả về một hàm accessor (ví dụ: `content.). Bạn phải gọi hàm này để truy cập nội dung phản ứng.

   Nếu bạn muốn sử dụng nội dung của mình trong một thuộc tính string, chẳng hạn như alt, title, href, aria-label, v.v., bạn phải gọi giá trị của hàm, như:

   html

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

6. 6

   Thay đổi ngôn ngữ của nội dung

   Tùy chọn

   Để 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 hook useLocale. Hàm này cho phép bạn đặt locale của ứng dụng và cập nhật nội dung tương ứng.

   src/components/LocaleSwitcher.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const { locale, setLocale, availableLocales } = useLocale();  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as Locales)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

7. 7

   Thêm định tuyến địa phương hóa vào ứng dụng của bạn

   Tùy chọn

   Mục đích của bước này là tạo các tuyến đường duy nhất cho mỗi ngôn ngữ. Điều này hữu ích cho SEO và URL thân thiện với SEO. Ví dụ:

   plaintext

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   - https://example.com/about- https://example.com/es/about- https://example.com/fr/about

   Để thêm định tuyến địa phương hóa vào ứng dụng của bạn, bạn có thể sử dụng @solidjs/router.

   Trước tiên, cài đặt các phụ thuộc cần thiết:

   bash

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   npm install @solidjs/router

   Sau đó, bọc ứng dụng của bạn bằng Router và xác định các tuyến đường của bạn bằng localeMap:

   src/index.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render(  () => (    <Router>      <App />    </Router>  ),  root!);

   src/App.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => (  <IntlayerProvider>    {localeMap(({ locale, urlPrefix }) => (      <Route        path={urlPrefix || "/"}        component={(props: any) => (          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>        )}      >        <Route path="/" component={Home} />        <Route path="/about" component={About} />      </Route>    ))}  </IntlayerProvider>);export default App;

8. 8

   Thay đổi URL khi ngôn ngữ thay đổi

   Tùy chọn

   Để thay đổi URL khi locale thay đổi, bạn có thể sử dụng prop onLocaleChange được cung cấp bởi hook useLocale. Bạn có thể sử dụng các hook useNavigate và useLocation từ @solidjs/router để cập nhật đường dẫn URL.

   src/components/LocaleSwitcher.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const location = useLocation();  const navigate = useNavigate();  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (loc) => {      const pathWithLocale = getLocalizedUrl(location.pathname, loc);      navigate(pathWithLocale);    },  });  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as any)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

9. 9

   Chuyển đổi thuộc tính Ngôn ngữ và Hướng của HTML

   Tùy chọn

   Cập nhật các thuộc tính lang và dir của thẻ <html> để khớp với locale hiện tại để hỗ trợ khả năng truy cập và SEO.

   src/App.tsx

   Sao chép nội dung

   Sao chép mã

   Sao chép mã vào clipboard

   import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => {  const { locale } = useLocale();  createEffect(() => {    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    // ... Nội dung ứng dụng của bạn  );};

10. 10

    Tạo thành phần Liên kết Địa phương hóa

    Tùy chọn

    Tạo một thành phần Link tùy chỉnh tự động thêm tiền tố các URL nội bộ bằng ngôn ngữ hiện tại.

    src/components/Link.tsx

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => props.href.startsWith("http");  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

11. 11

    Render Markdown

    Tùy chọn

    Intlayer hỗ trợ render nội dung Markdown trực tiếp trong ứng dụng Solid của bạn bằng cách sử dụng trình phân tích cú pháp nội bộ riêng. Theo mặc định, Markdown được xử lý như văn bản thuần túy. Để render nó dưới dạng HTML phong phú, hãy bọc ứng dụng của bạn bằng MarkdownProvider.

    src/index.tsx

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render(  () => (    <MarkdownProvider>      <App />    </MarkdownProvider>  ),  root!);

    Sau đó bạn có thể sử dụng nó trong các thành phần của mình:

    tsx

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Render dưới dạng HTML qua MarkdownProvider */}      {content.markdownContent}    </div>  );};

12. 1

    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.

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

    Cập nhật vite.config.ts của bạn để bao gồm plugin intlayerCompiler:

    vite.config.ts

    Sao chép nội dung

    Sao chép mã

    Sao chép mã vào clipboard

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Thêm plugin trình biên dịch ],});

    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

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

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

Cấu hình Git

Khuyến nghị 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 bạn.

Để 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 bị thiếu.
• Xem trước nội dung dịch ngay trong dòng.
• Các hành động nhanh để dễ dàng tạo và cập nhật 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.

(Tuỳ chọn) Sitemap và robots.txt (sinh lúc build)

Intlayer cung cấp generateSitemap và getMultilingualUrls để định dạng sitemap.xml đa ngôn ngữ và robots.txt cho crawler rồi tự ghi vào public/. Thường chạy một script Node nhỏ trước Vite (ví dụ hook npm predev / prebuild).

Sitemap

Trình tạo sitemap của Intlayer tôn trọng cấu hình locale và thêm metadata cho crawler.

Sitemap hỗ trợ không gian tên xhtml:link (hreflang). Thay vì chỉ liệt kê URL phẳng, Intlayer nối hai chiều mọi bản địa phương của từng trang (ví dụ /about, /fr/about hoặc /about?lang=fr tùy chế độ routing).

Robots.txt

Dùng getMultilingualUrls để quy tắc Disallow áp dụng cho mọi biến thể URL của đường dẫn nhạy cảm.

1. Thêm generate-seo.mjs ở thư mục gốc dự án

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Cần cài intlayer để script import. Môi trường production đặt SITE_URL (ví dụ trong CI).

Nên dùng generate-seo.mjs cho ESM của Node. Nếu dùng generate-seo.js, đặt "type": "module" trong package.json hoặc bật ESM tương đương.

2. Chạy script trước Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Chỉnh lệnh nếu dùng pnpm hoặc yarn. Có thể gọi từ CI hoặc bước pipeline khác.

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 bên ngoài bằng cách sử dụng CMS.