Quốc tế hóa

Thêm hỗ trợ đa ngôn ngữ cho ứng dụng của bạn. Sử dụng Proyecta Content API để bản địa hóa nội dung biên tập, hoặc yêu cầu AI tích hợp trực tiếp một framework i18n vào code.

Proyecta hỗ trợ hai cách tiếp cận bổ trợ nhau để quốc tế hóa các ứng dụng bạn xây dựng:

1. Bản địa hóa nội dung qua Proyecta Content API — dành cho nội dung biên tập (bài blog, FAQ, bản sao marketing) cần được dịch sang nhiều ngôn ngữ
2. i18n ở tầng code thông qua một translation framework — dành cho chuỗi giao diện, ngày tháng, tiền tệ, và chuyển đổi locale khi chạy

Cả hai đều hoạt động ngay hôm nay. Bạn cần cái nào phụ thuộc vào thứ bạn đang dịch.

Bản thân Proyecta builder được tích hợp sẵn 24 locale, vì vậy sản phẩm này rất thành thạo về i18n. Các pattern tương tự cũng áp dụng cho những ứng dụng bạn xây dựng bên trong nó.

Tùy chọn 1: Bản địa hóa nội dung (Proyecta Content API)

Nếu bạn đang xây dựng một trang web thiên về nội dung — blog, knowledge base, trang marketing, danh mục sản phẩm — hãy sử dụng tính năng hỗ trợ locale tích hợp sẵn. Chỉ cần nói cho AI biết bạn hỗ trợ những ngôn ngữ nào ("Make the site available in English, Spanish and French") và nó sẽ đăng ký giúp bạn, với tiếng Anh là mặc định. Sau đó đọc nội dung theo ngôn ngữ của người dùng.

Ở phía frontend, các hook nội dung có kiểu dữ liệu của template sẽ tự động phân giải các trường đã được bản địa hóa cho bạn — truyền vào locale hiện tại của người dùng và mỗi trường localized sẽ trả về một giá trị đã được dịch duy nhất:

import { useCollection, useEntry } from '@/hooks/useContent';
import { useTranslation } from 'react-i18next';

function Blog({ slug }: { slug: string }) {
    const { i18n } = useTranslation();

    // List a collection in the current locale
    const { data: posts } = useCollection('posts', { locale: i18n.language });

    // Or read one entry by slug in the current locale
    const { data: post } = useEntry('posts', slug, { locale: i18n.language });

    // ...render posts / post
}

Phía sau, CMS sẽ đi theo một chuỗi fallback — locale được yêu cầu → các fallback đã cấu hình của nó → locale mặc định — và báo cáo code locale thực sự được phục vụ trên mỗi entry dưới dạng localeResolved. Bỏ qua locale trên các trang đơn ngôn ngữ và các trường sẽ trả về giá trị thô.

Đây là lựa chọn phù hợp khi:

• Các biên tập viên không viết code cần dịch nội dung
• Bạn muốn các bản dịch có thể được quản lý phiên bản
• Bạn cần publishing theo từng locale cụ thể (publishing theo lịch sắp ra mắt — hiện tại các entry yêu cầu publish thủ công qua API)

Xem Quản lý Nội dung để biết toàn bộ Content API.

Tùy chọn 2: Framework i18n ở tầng code

Đối với các chuỗi giao diện — nhãn, nút, thông báo lỗi, ngày tháng, tiền tệ — hãy yêu cầu AI tích hợp trực tiếp một framework i18n vào dự án của bạn:

Add internationalization to my app.
Support English, Spanish, French, and Arabic.
Add message catalogs in src/locales/.
Add a language switcher in the header.
Use locale-prefixed URLs like /en/about and /es/about.
Make sure RTL layout works correctly for Arabic.

AI sẽ:

1. Chọn một framework — AI sử dụng i18next kết hợp với react-i18next (tiêu chuẩn của Proyecta)
2. Tạo các file catalog trong src/locales/ (một JSON cho mỗi ngôn ngữ)
3. Bao bọc văn bản trong các lệnh gọi t() (từ hook useTranslation của react-i18next)
4. Thêm một component language switcher
5. Cấu hình URL routing với các tiền tố locale
6. Xử lý layout RTL (dir="rtl") cho tiếng Ả Rập, tiếng Do Thái, v.v.
7. Định dạng số, ngày tháng và tiền tệ theo từng locale

Tự động dịch với AI

Khi ngôn ngữ cơ sở của bạn đã sẵn sàng, AI rất hữu ích trong việc tạo ra các file catalog còn lại:

• "Translate every string in src/locales/en.json into Spanish, French, German, and Japanese. Use natural, idiomatic phrasing — don't translate brand names."
• "My app is fully built in English. Add Spanish translations for everything and an es/ route prefix."

Đối với nội dung quan trọng (văn bản pháp lý, y tế, tài chính), hãy để một dịch giả con người review kết quả của AI trước khi đưa lên production.

Kết hợp cả hai cách tiếp cận

Hầu hết các ứng dụng thực tế đều dùng cả hai: i18n ở tầng code cho phần chrome giao diện (nút bấm, thông báo lỗi, điều hướng), và Content API cho nội dung biên tập (bài viết, mô tả sản phẩm). Chúng hoạt động song song một cách gọn gàng — framework i18n xử lý các file catalog lúc build, Content API phục vụ các entry đã bản địa hóa khi chạy.

Các thực hành tốt nhất

1. Chọn ngôn ngữ cơ sở và hoàn thiện bản sao trước. Dịch một nội dung đang thay đổi liên tục rất mệt mỏi.
2. Dịch theo lô. Đừng dịch từng chút một theo tiến độ — hãy chờ cho đến khi một tính năng ổn định.
3. Kiểm tra RTL sớm nếu bạn hỗ trợ tiếng Ả Rập hoặc tiếng Do Thái. Lỗi RTL thường không lộ ra cho đến khi bạn thực sự kiểm tra.
4. Thêm lang và dir vào <html>. Trình duyệt và trình đọc màn hình phụ thuộc vào điều này.
5. Dùng Intl để định dạng. Đừng tự viết code định dạng ngày tháng hay tiền tệ — hãy dùng Intl.DateTimeFormat, Intl.NumberFormat.

Sắp ra mắt

• Giao diện quản lý locale tích hợp trong builder — chọn locale, xem mức độ phủ bản dịch, chỉnh sửa catalog mà không cần rời khỏi Proyecta
• Tự động dịch khi lưu cho các chuỗi mới
• Các template dự án sẵn sàng i18n với framework đã được cấu hình trước