Intlayer v7 Mới - Có gì mới?

Chào mừng đến với Intlayer v7! Phiên bản lớn này giới thiệu các cải tiến đáng kể về hiệu suất, an toàn kiểu và trải nghiệm nhà phát triển. Dưới đây là những điểm nổi bật, kèm theo ghi chú di chuyển và ví dụ thực tiễn.

Mục lục

Những điểm nổi bật

• Chiến lược lưu bộ nhớ đệm để xây dựng nhanh hơn
• Cải tiến việc tạo kiểu TypeScript với các kiểu riêng cho từng ngôn ngữ
• Tối ưu gói: Các ngôn ngữ được lưu dưới dạng chuỗi thay vì enum
• Các chế độ định tuyến mới: prefix-no-default, prefix-all, no-prefix, search-params
• Lưu trữ ngôn ngữ tuân thủ GDPR với localStorage làm mặc định
• Cấu hình lưu trữ linh hoạt: cookies, localStorage, sessionStorage, hoặc kết hợp nhiều loại
• Kích thước bundle Visual Editor giảm 30%
• Tùy chọn cấu hình middleware được cải thiện
• Cập nhật hành vi lệnh fill để quản lý nội dung tốt hơn
• Tăng cường độ ổn định với việc cập nhật đầy đủ các tệp khai báo nội dung
• Quản lý thử lại thông minh để đảm bảo độ chính xác dịch thuật
• Xử lý song song để tăng tốc quá trình dịch thuật
• Chia nhỏ thông minh để xử lý các tệp lớn trong giới hạn ngữ cảnh AI

Hiệu suất: Bộ nhớ đệm để tăng tốc quá trình build

Thay vì xây dựng lại các khai báo nội dung với esbuild trong mỗi lần build, phiên bản v7 triển khai một chiến lược lưu bộ nhớ đệm giúp tăng tốc quá trình build.

npx intlayer build

Hệ thống lưu bộ nhớ đệm mới:

• Lưu trữ các khai báo nội dung đã biên dịch để tránh xử lý trùng lặp
• Phát hiện thay đổi và chỉ xây dựng lại các tệp đã sửa đổi
• Giảm đáng kể thời gian build cho các dự án lớn

TypeScript: Tạo kiểu riêng cho từng ngôn ngữ

Kiểu TypeScript giờ đây được tạo riêng cho từng ngôn ngữ, cung cấp kiểu mạnh hơn và loại bỏ các kiểu hợp nhất (union types) giữa các ngôn ngữ.

Hành vi v6:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }

Hành vi v7:

const content = getIntlayer("my-title-content", "en");// typeof content = { title: "My title" }

Lợi ích:

• Tự động hoàn thành chính xác hơn trong IDE của bạn
• An toàn kiểu tốt hơn, không bị lẫn lộn kiểu giữa các ngôn ngữ
• Cải thiện hiệu suất bằng cách giảm độ phức tạp kiểu

Tối ưu gói: Các ngôn ngữ dưới dạng chuỗi

Kiểu Locales không còn là enum nữa, điều này có nghĩa là nó hoàn toàn có thể tree-shake và sẽ không làm phình to gói của bạn với hàng nghìn bản ghi ngôn ngữ không sử dụng.

v6:

import { Locales } from "intlayer";// Enum bao gồm tất cả các ngôn ngữ -> không thể tree-shakeconst locale: Locales = Locales.ENGLISH;

v7:

import { Locales, Locale } from "intlayer";// Kiểu chuỗi -> hoàn toàn có thể tree-shakeconst locale: Locale = Locales.ENGLISH;

Vì Locales không còn là enum nữa, bạn sẽ phải thay đổi kiểu từ Locales thành Locale để lấy locale dưới dạng kiểu.

Xem chi tiết triển khai để biết thêm thông tin.

Chế độ định tuyến mới cho sự linh hoạt hơn

Phiên bản v7 giới thiệu cấu hình routing.mode thống nhất thay thế cho các tùy chọn prefixDefault và noPrefix trước đây, cung cấp kiểm soát chi tiết hơn đối với cấu trúc URL.

Các chế độ định tuyến có sẵn

• prefix-no-default (mặc định): Ngôn ngữ mặc định không có tiền tố, các ngôn ngữ khác có
  • /dashboard (en) hoặc /fr/dashboard (fr)
• prefix-all: Tất cả các ngôn ngữ đều có tiền tố
  • /en/dashboard (en) hoặc /fr/dashboard (fr)
• no-prefix: Không có tiền tố locale trong URL (locale được xử lý qua lưu trữ/headers)
  • /dashboard cho tất cả các locale
• search-params: Locale được truyền dưới dạng tham số truy vấn
  • /dashboard?locale=en hoặc /dashboard?locale=fr

Cấu hình cơ bản

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default", // mặc định  },};

Tuân thủ GDPR: lưu trữ localStorage / cookies

Phiên bản v7 ưu tiên quyền riêng tư của người dùng bằng cách sử dụng localStorage làm cơ chế lưu trữ mặc định thay vì cookies. Thay đổi này giúp tuân thủ GDPR bằng cách tránh yêu cầu đồng ý cookie cho tùy chọn locale.

Các tùy chọn cấu hình lưu trữ

Trường routing.storage mới cũng có sẵn bên cạnh các tùy chọn trước đó như middleware.cookieName và middleware.serverSetCookie, cung cấp các cấu hình lưu trữ linh hoạt:

// Vô hiệu hóa lưu trữstorage: false// Các loại lưu trữ đơn giảnstorage: 'cookie'storage: 'localStorage'storage: 'sessionStorage'// Cookie với các thuộc tính tùy chỉnhstorage: {  type: 'cookie',  name: 'custom-locale',  domain: '.example.com',  secure: true,  sameSite: 'strict'}// localStorage với khóa tùy chỉnhstorage: {  type: 'localStorage',  name: 'custom-locale'}// Nhiều loại lưu trữ để dự phòngstorage: ['cookie', 'localStorage']

Ví dụ cấu hình tuân thủ GDPR

Dành cho các ứng dụng sản xuất cần cân bằng giữa chức năng và tuân thủ GDPR:

// intlayer.config.tsexport default {  internationalization: {    locales: ["en", "fr", "es"],    defaultLocale: "en",  },  routing: {    mode: "prefix-no-default",    storage: [      {        type: "localStorage", // Lưu trữ chính (không cần sự đồng ý)        name: "user-locale",      },      {        type: "cookie", // Lưu trữ cookie tùy chọn (cần sự đồng ý)        name: "user-locale",        secure: true,        sameSite: "strict",        httpOnly: false,      },    ],  },};

Bật / tắt lưu trữ cookie

Ví dụ sử dụng React / Next.js:

Có thể được định nghĩa toàn cục:

<IntlayerProvider isCookieEnabled={false}>  <App /></IntlayerProvider>

Có thể ghi đè cục bộ cho từng hook:

const { setLocale } = useLocale({ isCookieEnabled: false });setLocale("en");

Lưu ý: Cookie được bật theo mặc định. Lưu ý: Kiểm tra yêu cầu cookie GDPR cho trường hợp sử dụng cụ thể của bạn.

Trình chỉnh sửa trực quan: Gói nhỏ hơn 30%

Gói Trình chỉnh sửa trực quan đã được tối ưu hóa để nhỏ hơn 30% so với phiên bản trước, nhờ vào:

• Cải thiện hiệu suất trình chỉnh sửa mã
• Loại bỏ các phụ thuộc không cần thiết trên các gói lõi của Intlayer
• Cải tiến tree-shaking và đóng gói module

Điều này giúp giảm thời gian tải xuống và cải thiện hiệu suất chạy ứng dụng của bạn.

Định dạng Code Tự động: cấu hình formatCommand

v7 giới thiệu tùy chọn formatCommand trong cấu hình editor, cho phép bạn tự động định dạng các tệp nội dung khi chúng được ghi bởi Intlayer. Điều này đảm bảo kiểu code và định dạng nhất quán trên các tệp khai báo nội dung của bạn.

Nếu không được đặt, Intlayer sẽ cố gắng phát hiện lệnh định dạng tự động. Bằng cách cố gắng giải quyết các lệnh sau: prettier, biome, eslint.

Cấu hình

Tùy chọn formatCommand chấp nhận một mẫu chuỗi trong đó {{file}} sẽ được thay thế bằng đường dẫn tệp thực tế:

export default {  content: {    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',  },};

Các formatter được hỗ trợ

Bạn có thể sử dụng bất kỳ code formatter nào chấp nhận đường dẫn tệp làm đối số:

Sử dụng Biome:

formatCommand: 'bun x biome format "{{file}}" --write --log-level none';

Sử dụng Prettier:

formatCommand: 'npx prettier --write "{{file}}" --log-level silent';

Sử dụng ESLint:

formatCommand: 'npx eslint --fix "{{file}}" --quiet';

Sử dụng built-in formatter của Bun:

formatCommand: 'bun format "{{file}}"';

Lợi ích

• Định dạng nhất quán: Tất cả các tệp nội dung được tự động định dạng theo các hướng dẫn kiểu dáng của dự án của bạn
• Trải nghiệm nhà phát triển: Không cần phải định dạng tệp theo cách thủ công sau khi Intlayer ghi chúng
• Tính nhất quán của nhóm: Đảm bảo tất cả các thành viên trong nhóm có cùng định dạng được áp dụng cho các tệp nội dung
• Tích hợp CI/CD: Các tệp nội dung duy trì định dạng nhất quán trong các quy trình làm việc tự động

Cách hoạt động

Khi Intlayer ghi hoặc cập nhật một tệp khai báo nội dung (.content.ts, .content.js, v.v.), nó tự động chạy lệnh định dạng được chỉ định trên tệp. Trình giữ chỗ {{file}} được thay thế bằng đường dẫn tệp thực tế và lệnh được thực thi trong thư mục cơ sở của dự án.

Cấu hình Dictionary: Tổ chức và cấu trúc tốt hơn

v7 giới thiệu một phần cấu hình dictionary mới được dành riêng cung cấp tổ chức tốt hơn cho các cài đặt liên quan đến dictionary và quản lý nội dung được cải thiện.

Cấu trúc cấu hình dictionary mới

Thuộc tính fill đã được chuyển từ phần content sang phần dictionary mới, cung cấp sự tách biệt rõ ràng hơn về các mối quan tâm:

Cấu hình v6:

export default {  content: {    autoFill: "./{{fileName}}.content.json",    contentDir: ["src"],  },};

Cấu hình v7:

export default {  content: {    contentDir: ["src"],  },  dictionary: {    fill: "./{{fileName}}.content.json",  },};

Lợi ích của cấu trúc mới

• Tổ chức rõ ràng hơn: Các cài đặt dành riêng cho từ điển hiện được nhóm lại với nhau
• Tách biệt mối quan tâm tốt hơn: Khám phá nội dung và các hoạt động từ điển được tách biệt rõ ràng
• Khả năng bảo trì được cải thiện: Dễ dàng hiểu và sửa đổi các cấu hình liên quan đến từ điển
• Khả năng mở rộng trong tương lai: Phần từ điển có thể chứa các cài đặt dành riêng cho từ điển bổ sung
• Quản lý từ điển toàn diện: Bao gồm các thuộc tính như title, live, priority, tags, version và description để tạo và quản lý các từ điển mới

Cách sử dụng cấu hình

Cấu hình từ điển phục vụ hai mục đích chính:

1. Giá trị mặc định: Xác định giá trị mặc định khi tạo các tệp khai báo nội dung
2. Hành vi dự phòng: Cung cấp giá trị dự phòng khi các trường cụ thể không được xác định, cho phép bạn xác định hành vi hoạt động của từ điển một cách toàn cầu

Phần từ điển bao gồm các thuộc tính toàn diện để quản lý từ điển:

• fill: Hành vi tự động điền cho việc tạo nội dung
• title: Tiêu đề mặc định cho các từ điển mới
• live: Cấu hình đồng bộ hóa trực tiếp cho các bản cập nhật theo thời gian thực
• priority: Cài đặt ưu tiên để phân giải từ điển
• tags: Thẻ mặc định để tổ chức nội dung
• version: Quản lý phiên bản cho các bản cập nhật từ điển
• description: Mô tả mặc định cho nội dung mới

Để biết thêm thông tin về các tệp khai báo nội dung và cách áp dụng các giá trị cấu hình, hãy xem Tài liệu tệp nội dung.

Lệnh fill: Hành vi cập nhật để quản lý nội dung tốt hơn

Phiên bản v7 giới thiệu hành vi cải tiến cho lệnh fill, cung cấp quản lý nội dung linh hoạt và dễ dự đoán hơn:

Hành vi fill mới

• fill: true - Ghi đè tệp hiện tại với nội dung đã điền cho tất cả các ngôn ngữ
• fill: "path/to/file" - Điền vào tệp được chỉ định mà không sửa đổi tệp hiện tại
• fill: false - Vô hiệu hóa hoàn toàn tính năng tự động điền

Hỗ trợ nâng cao cho các cấu trúc nội dung phức tạp

Lệnh fill hiện hỗ trợ các cấu trúc khai báo nội dung phức tạp, bao gồm:

• Đối tượng ghép: Các khai báo nội dung tham chiếu đến các đối tượng khác
• Nội dung giải cấu trúc: Nội dung sử dụng các mẫu giải cấu trúc
• Tham chiếu lồng nhau: Các đối tượng gọi lẫn nhau trong các hệ thống phân cấp phức tạp
• Cấu trúc nội dung động: Nội dung có các thuộc tính điều kiện hoặc tính toán

Lợi ích

• Ý định rõ ràng hơn: Hành vi giờ đây rõ ràng hơn về những gì được sửa đổi
• Tách biệt tốt hơn: Các tệp nội dung có thể được giữ riêng biệt với các bản dịch đã điền
• Quy trình làm việc cải tiến: Các nhà phát triển có nhiều quyền kiểm soát hơn về nơi lưu trữ các bản dịch
• Hỗ trợ cấu trúc phức tạp: Xử lý các kiến trúc nội dung tinh vi với nhiều đối tượng liên kết phức tạp

Ví dụ sử dụng

// Ghi đè tệp hiện tại với tất cả các ngôn ngữconst content = {  key: "example",  fill: true, // Ghi đè tệp này  content: {    title: "Hello World",  },};// Điền vào tệp riêng biệt mà không sửa đổi tệp hiện tạiconst content = {  key: "example",  fill: "./translations.json", // Tạo/cập nhật translations.json  content: {    title: "Hello World",  },};// Vô hiệu hóa tự động điềnconst content = {  key: "example",  fill: false, // Không tự động điền  content: {    title: "Hello World",  },};// Cấu trúc nội dung phức tạp với các đối tượng ghépconst sharedContent = {  buttons: {    save: "Lưu",    cancel: "Hủy",  },};const content = {  key: "complex-example",  fill: true,  content: {    // Tham chiếu đến các đối tượng khác    sharedContent,    // Nội dung được giải cấu trúc    ...sharedContent,    // Tham chiếu lồng nhau    sections: [      {        ...sharedContent.buttons,        header: "Phần 1",      },    ],  },};

Tăng cường độ ổn định và quản lý bản dịch

Phiên bản v7 giới thiệu một số cải tiến để làm cho việc dịch nội dung trở nên đáng tin cậy và hiệu quả hơn:

Cập nhật đầy đủ tệp khai báo nội dung

Hệ thống hiện cập nhật các tệp .content.{ts,js,cjs,mjs} thay vì cập nhật từng phần, đảm bảo:

• Toàn vẹn dữ liệu: Việc viết lại toàn bộ file ngăn ngừa các cập nhật một phần có thể làm hỏng nội dung
• Tính nhất quán: Tất cả các ngôn ngữ được cập nhật đồng thời, duy trì sự đồng bộ
• Độ tin cậy: Giảm nguy cơ các file nội dung bị thiếu hoặc bị lỗi định dạng

Quản lý thử lại thông minh

Cơ chế thử lại mới ngăn việc đẩy nội dung với định dạng sai, và tránh làm gián đoạn toàn bộ quá trình điền nếu một yêu cầu thất bại.

Song song hóa để xử lý nhanh hơn

Các thao tác dịch thuật hiện chạy theo hàng đợi để thực thi song song. Điều này tăng tốc đáng kể quá trình.

Chia nhỏ thông minh cho các file lớn

Chiến lược chia nhỏ nâng cao xử lý các file nội dung lớn mà không vượt quá giới hạn ngữ cảnh của AI:

Ví dụ quy trình làm việc

// File nội dung lớn được tự động chia nhỏconst content = {  key: "large-documentation",  fill: true,  content: {    // Nội dung lớn được tự động chia nhỏ để xử lý AI    introduction: "..." // hơn 5000 ký tự    sections: [      // Nhiều phần lớn    ]  }};

Hệ thống tự động:

1. Phân tích kích thước và cấu trúc nội dung
2. Chia nhỏ nội dung phù hợp
3. Xử lý các phần song song
4. Xác thực và thử lại nếu cần
5. Tái tạo lại file hoàn chỉnh

Ghi chú di chuyển từ v6

Các cấu hình đã loại bỏ

• middleware.cookieName: Thay thế bằng routing.storage
• middleware.serverSetCookie: Thay thế bằng routing.storage
• middleware.prefixDefault: Thay thế bằng routing.mode
• middleware.noPrefix: Thay thế bằng routing.mode

Cấu hình mới

• editor.formatCommand: Tùy chọn mới để tự động định dạng mã trong các tệp nội dung

Bản đồ di chuyển

Bản đồ cấu hình

Ví dụ di chuyển

Trước (v6):

export default {  middleware: {    headerName: "x-intlayer-locale",    cookieName: "intlayer-locale",    prefixDefault: false,    basePath: "",    serverSetCookie: "always",    noPrefix: false,  },};

Sau (v7):

export default {  routing: {    mode: "prefix-no-default",    storage: "localStorage", // hoặc 'cookie' nếu bạn cần lưu trữ bằng cookie    headerName: "x-intlayer-locale",    basePath: "",  },};

Bản đồ nội dung từ điển

Ví dụ di chuyển

Trước (v6):

const content = {  key: "example",  autoFill: true, // Viết lại file này  content: {    title: "Hello World",  },};

Sau (v7):

const content = {  key: "example",  fill: true, // Ghi đè file này  content: {    title: "Hello World",  },};

Ghi chú di chuyển từ v5 lên v6

Xem ghi chú di chuyển từ v5 lên v6 để biết thêm thông tin.

Liên kết hữu ích

• Tham khảo Cấu hình
• Tài liệu Middleware
• Kiểu TypeScript
• Hướng dẫn Cookie GDPR