en

blog

Blog song ngữ trên Next.js static export: translationOf, hreflang và gate fail build

Mỗi bài có 2 file Markdown nối nhau bằng một dòng translationOf. Map URL, hreflang, nút đổi ngôn ngữ và gate fail build đều suy ra từ dòng đó, không dùng i18n của Next.

Ngày đăng
Next.js 16i18nhreflangStatic export
2 thẻ file ngang hàng gắn nhãn vi và en, nối với nhau bằng mũi tên 2 đầu có nhãn translationOf, bên dưới là 3 thanh nhỏ ghi hreflang vi, en và x-default

Blog song ngữ trên static export chỉ cần một dòng frontmatter ở bản Anh để nối cặp. Map URL, hreflang, nút đổi ngôn ngữ và gate fail build đều suy ra từ dòng đó, nên file bản Việt không phải sửa khi thêm bản dịch. Plan làm bản Anh của site này chốt không dùng i18n của Next, vì static export không hỗ trợ nó: ngôn ngữ của trang suy ra thẳng từ slug.

Bản Anh khai translationOf, bản Việt không cần sửa

Cây content/en/ lặp lại cây content/. lib/mdx-files.js làm phẳng thư mục blog như bản Việt: content/blog/x.md ra /x, content/en/blog/y.md ra /en/y. Một catch-all pages/[[...slug]].js phục vụ cả 2 bản, như mô tả trong kiến trúc site Next.js chạy bằng Markdown. Ngôn ngữ suy ra từ phần tử đầu của slug:

js
export const localeOfSlug = (slug) => (Array.isArray(slug) && slug[0] === 'en' ? 'en' : 'vi')

Cặp nối bằng một dòng đặt ngay sau layout: của file Anh. Đây là frontmatter thật của bản Anh bài về subagent:

yaml
---
layout: BlogPost
translationOf: /toi-uu-subagent-claude-code-sdd
date: '2026-11-04'
updated: '2026-11-11'
---

Slug Anh của bài đó là claude-code-subagent-cost-optimization, khác hẳn slug Việt, vì nó mang keyword người đọc Anh gõ vào Google. translationOf là chuỗi URL chứ không phải tên file, nên 2 slug không cần giống nhau. Ngoại lệ duy nhất là slug dự án, vì đó là tên thương hiệu.

Dòng translationOf còn được 2 chỗ khác đọc. scripts/generate-sitemaps.js dùng nó để in 3 thẻ xhtml:link cho mỗi URL có cặp. Gate nguồn tìm sidecar của bản Việt qua nó, nên bản Anh không có sidecar riêng; chỉ khi con số đổi dạng (ví dụ "150 nghìn" thành "150,000") mới cần thêm <slug-anh>.sources.yml.

lib/translations.js dựng map hai chiều

Chỉ file Anh khai cặp, nên map dựng bằng cách quét content/en/**. Mỗi cặp ghi 2 entry, nên tra từ phía nào cũng ra phía kia:

js
async function buildMap() {
  if (cache) return cache
  const map = new Map()
  for (const { slug, filePath } of await getFiles('en', getMdxOptions())) {
    const { translationOf } = matter.read(filePath).data
    if (!translationOf) continue
    map.set(toUrl(slug), translationOf)
    map.set(translationOf, toUrl(slug))
  }
  cache = map
  return map
}

export async function getAlternates(slug) {
  const self = slug.length ? toUrl(slug) : '/'
  const other = (await buildMap()).get(self)
  const isEn = slug[0] === 'en'
  if (!other) return isEn ? { en: self } : { vi: self }
  return isEn ? { vi: other, en: self } : { vi: self, en: other }
}

Trang không có cặp nhận về object chỉ có 1 key. Đó là tín hiệu để lớp sau không in gì. getStaticProps gọi hàm này rồi đẩy locale và alternates vào props của trang.

hreflang chỉ in khi cả 2 phía tồn tại

components/Seo.jsx nhận alternates và chỉ dựng languageAlternates khi có đủ cả vi lẫn en:

jsx
const languageAlternates =
  alternates.vi && alternates.en
    ? [
        { hrefLang: 'vi', href: abs(alternates.vi) },
        { hrefLang: 'en', href: abs(alternates.en) },
        { hrefLang: 'x-default', href: abs(alternates.vi) },
      ]
    : undefined

Cặp đủ thì ra 3 thẻ, x-default trỏ bản Việt. Thiếu một phía thì không ra thẻ nào, và og:locale:alternate cũng theo đúng điều kiện đó. Trang danh sách /page/N bị ép alternates={} trong pages/[[...slug]].js: số trang của 2 ngôn ngữ có thể lệch nhau, nên plan chọn không phát hreflang cho chúng.

Quy tắc này khớp với thực tế của site: trang dự án và trang marketing chỉ có một ngôn ngữ vẫn hợp lệ khi không có hreflang nào. Chỉ số thẻ lệch (1 hoặc 2) mới là lỗi.

LanguageSwitch không tự chuyển ngôn ngữ

Người đọc đổi ngôn ngữ bằng một nút tròn cạnh nút theme. Logic chọn đích gói trong 2 dòng của components/LanguageSwitch.jsx:

jsx
const target = locale === 'en' ? 'vi' : 'en'
const href = alternates?.[target] || (target === 'en' ? '/en' : '/')

Có cặp thì link sang bài kia, không có thì về trang chủ của ngôn ngữ kia. Site không redirect theo ngôn ngữ browser: plan chốt ngày 31/10/2026 là chỉ có nút đổi ngôn ngữ và thẻ hreflang.

<html lang> đặt trong pages/_document.js từ pageProps.locale. Plan ghi rõ đừng suy locale từ window.location hay navigator.language: server và client phải cùng giá trị, không thì dính hydration #418.

check-i18n fail build khi thiếu bản Anh

scripts/check-i18n.js chạy trong prebuild, trước cả bước sinh search index. Với mỗi file dưới content/en/, content/en/blog/ và content/en/projects/, nó kiểm:

  • translationOf có mặt, là chuỗi bắt đầu bằng /, và không phải /en hay /en/....
  • Nó khớp một file Việt thật, và bằng đúng URL thật của file đó.
  • Bài blog trỏ bài blog, dự án trỏ dự án, trang trỏ trang.
  • Mỗi URL Việt chỉ có một bản Anh.
  • date và updated của 2 bản trùng nhau, vì chúng quyết định lastmod và thứ tự bài.

Rồi tới chiều ngược lại, từ bản Việt:

js
for (const f of mdIn(path.join(C, 'blog'))) {
  const url = '/' + f.replace(/\.md$/, '')
  if (!paired.has(url)) (STRICT ? errors : warnings).push(`content/blog/${f}: chưa có bản tiếng Anh`)
}

Với STRICT = true, bài blog mới thiếu bản Anh làm npm run build dừng trước khi next build chạy. Khi mọi cặp đều khớp, gate in một dòng tóm tắt dạng check-i18n: <số> cặp; có lỗi thì in từng lỗi kèm đường dẫn file rồi thoát với mã 1.

Gate này không cứng ngay từ đầu. Ở đợt 1 và 2 của plan, STRICT là false và nó chỉ cảnh báo, vì 18 bài cũ chưa dịch. Plan bật STRICT = true ở cuối đợt 3, khi cả 18 bài đã có cặp, rồi deploy ngày 01/11/2026. Bật cứng trước đó thì mọi build đều đỏ.

Chỗ gate không bắt được

check-i18n so ngày tháng chứ không so nội dung. Sửa một con số ở bản Việt mà quên bản Anh thì gate vẫn xanh. Luật phải giữ bằng tay: đổi fact thì sửa cả 2 bản trong cùng commit, cùng updated.

Đổi slug Việt thì translationOf của bản Anh thành chuỗi chết, và gate báo không khớp file nào. Cover có chữ Việt cần bản Anh riêng, og:image phải là PNG, hreflang phải trỏ ngược lại đúng trang: 3 thứ này gate trên không nhìn thấy, vì nó đọc source chứ không đọc HTML đã build. Phần kiểm trên HTML nằm ở bài về check:seo và check:links.

Bài viết liên quan

tất cả bài viết →