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
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:
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:
---
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:
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:
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:
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:
translationOfcó mặt, là chuỗi bắt đầu bằng/, và không phải/enhay/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.
datevàupdatedcủa 2 bản trùng nhau, vì chúng quyết địnhlastmodvà thứ tự bài.
Rồi tới chiều ngược lại, từ bản Việt:
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 →- check:seo và check:links trên out/ của Next.js: kiểm HTML đã build, không kiểm source2 gate chạy trong postbuild đọc thẳng out/**/*.html: canonical, og:image, hreflang hai chiều, title trùng, xhtml:link của sitemap, link nội bộ chết. Lỗi làm build fail trước khi deploy.đọc tiếp →
- Gỡ @tailwindcss/aspect-ratio: lỗi im lặng khiến mọi ảnh cover cao 0pxPlugin aspect-ratio thay theme.aspectRatio nên Tailwind core ngừng phát aspect-video. Hộp ảnh sập còn 0px, mọi cover vô hình, build vẫn xanh. Đây là cách tôi lần ra và chặn lỗi này.đọc tiếp →
- Critical CSS cho Next.js static: critters, font và màn hình đầu trên PSI mobileSite Next.js static của tôi dính 3 bẫy PSI mobile: CSS chặn render, font inline tải sớm và JS chờ ở màn hình đầu. Đây là cách xử lý từng cái, bắt đầu từ critical CSS bằng critters ở postbuild.đọc tiếp →
- Bỏ server: chuyển site Next.js tĩnh sang Cloudflare Workers Static AssetsSite này chỉ là HTML, JS và ảnh, vậy mà từng nằm trên một VPS 2 GB RAM chung với khoảng 28 site khác. Cách chuyển nó sang Workers Static Assets: dịch cấu hình nginx sang _redirects và _headers, vì sao request không tính vào hạn mức gói Free, và 2 chỗ vấp sau ngày chuyển.đọc tiếp →