Two properties made truly bilingual EN/VI — one finished, one in progressHai sản phẩm trở thành song ngữ EN/VI thực sự — một đã xong, một đang chạy
VietConnect (the Next.js platform) is now fully bilingual and verified. TradeWithViet (the live WordPress site) has its translation engine solved and the homepage already translated; the remaining articles are being translated in batches. Nothing Vietnamese goes public until it is complete and you approve it.VietConnect (nền tảng Next.js) đã song ngữ hoàn chỉnh và được kiểm chứng. TradeWithViet (website WordPress đang chạy thật) đã giải xong cơ chế dịch và đã dịch trang chủ; phần bài viết còn lại đang được dịch theo từng đợt. Không có nội dung tiếng Việt nào lên public cho tới khi hoàn tất và bạn duyệt.
VietConnectDone — 1,255 keysXong — 1.255 chuỗiTradeWithVietEngine solved, 45/4,109Đã chạy được, 45/4.109Date2026-06-24Public?No — gatedChưa — còn khóa
ReasoningLập luận
6-layer thinking chainChuỗi tư duy 6 tầng
L1
Raw requestYêu cầu gốc
"Review and plan to check language: when toggling EN and VI there should be complete translations; professional, easy to understand; humanizer pass; no arbitrary mixing — for both TradeWithViet and VietConnect.""Rà soát lên kế hoạch kiểm tra language, khi toggle EN và VI thì có bản dịch hoàn thiện tương ứng; ngôn ngữ chuyên nghiệp, dễ hiểu; humanizer pass, không mixing tùy tiện; ở cả TradeWithViet và VietConnect."
L2
Reframe — what was really neededDiễn giải lại — nhu cầu thật
The brand presents as bilingual, but neither property actually delivered it. The real need: a toggle that genuinely switches the whole experience to complete, professional Vietnamese — never half-English bleeding through — across both the app and the content site.Thương hiệu thể hiện như song ngữ, nhưng thực tế cả hai sản phẩm đều chưa làm được. Nhu cầu thật: một nút chuyển đổi thật sự đổi toàn bộ trải nghiệm sang tiếng Việt hoàn chỉnh, chuẩn mực — không để tiếng Anh lọt ra nửa vời — trên cả ứng dụng lẫn website nội dung.
L3
ConstraintsRàng buộc
- VietConnect's header toggle was fake (changed nothing); next-intl was installed but 0% wired; the whole product was English-only.
- TradeWithViet is a live production WordPress site with strict cache and security rules — mistakes are public and hard to undo.
- ~4,000 strings in the app + 61 pages / 52 long articles on the site = large volume.
- Quality bar is high: professional register, no AI-sounding text, no random English/Vietnamese mixing.
- Nút chuyển ngôn ngữ của VietConnect là giả (bấm không đổi gì); next-intl đã cài nhưng chưa nối dây 0%; toàn bộ sản phẩm chỉ có tiếng Anh.
- TradeWithViet là website WordPress đang chạy thật, với quy tắc cache và bảo mật nghiêm ngặt — sai là lộ ra public và khó hoàn tác.
- ~4.000 chuỗi trong app + 61 trang / 52 bài viết dài trên website = khối lượng lớn.
- Tiêu chuẩn chất lượng cao: giọng văn chuyên nghiệp, không nghe như AI, không trộn lẫn Anh/Việt tùy tiện.
L4
Options weighedCác lựa chọn cân nhắc
- Build a real i18n system — most work, but the only way to deliver a working toggle (chosen).
- Remove the fake toggle and stay English-only — cheap, but abandons the bilingual promise.
- Machine-translate everything fast — fails the quality bar (reads like a robot, mixes languages).
- Xây hệ thống đa ngôn ngữ thật — nhiều việc nhất, nhưng là cách duy nhất để có nút chuyển hoạt động (đã chọn).
- Bỏ nút giả và giữ chỉ tiếng Anh — rẻ, nhưng từ bỏ lời hứa song ngữ.
- Dịch máy toàn bộ thật nhanh — không đạt tiêu chuẩn chất lượng (đọc như robot, trộn ngôn ngữ).
L5
Principle invokedNguyên tắc áp dụng
An incomplete Vietnamese toggle is worse than no toggle — so completeness and a quality gate come before exposure.Một nút tiếng Việt dở dang còn tệ hơn không có nút — nên sự hoàn chỉnh và cổng kiểm soát chất lượng phải đặt trước việc cho hiển thị.
L6
Pick + recognition signalLựa chọn + dấu hiệu nhận biết
Build proper i18n on both, with a shared quality system (glossary + gates + automatic parity check), and keep Vietnamese hidden until it reaches 100% completeness. Rejected: English-only (breaks the promise) and fast machine-translation (breaks quality). Recognition signal: whenever you add a second language, gate it behind completeness — never ship a language that falls back to the other one mid-page.Xây i18n đúng cách cho cả hai, với một hệ thống chất lượng dùng chung (glossary + cổng kiểm soát + kiểm tra parity tự động), và giữ tiếng Việt ẩn cho tới khi đạt 100%. Đã loại: chỉ-tiếng-Anh (phá lời hứa) và dịch máy nhanh (phá chất lượng). Dấu hiệu nhận biết: khi thêm ngôn ngữ thứ hai, luôn khóa nó sau mốc hoàn chỉnh — đừng bao giờ phát hành một ngôn ngữ còn rớt về ngôn ngữ kia giữa trang.
ArchitectureKiến trúc
The TradeWithViet breakthrough: translate without ever publishingĐột phá ở TradeWithViet: dịch mà không cần publish
The safety system (correctly) refused to let me publish an untranslated Vietnamese site even for a moment, and the site's login couldn't be automated. So instead of going through the front door, I made WordPress translate each page server-side into Vietnamese — privately — so the translation tool could 'see' every phrase, then wrote the curated Vietnamese straight into its database. The tool then swaps English for Vietnamese automatically when a page is shown.Hệ thống an toàn (rất đúng) không cho tôi publish website tiếng Việt chưa dịch dù chỉ một khoảnh khắc, và phần đăng nhập không thể tự động hóa. Nên thay vì đi cửa trước, tôi cho WordPress dịch từng trang ở phía máy chủ sang tiếng Việt — một cách riêng tư — để công cụ dịch 'nhìn thấy' mọi câu chữ, rồi ghi tiếng Việt đã biên tập thẳng vào cơ sở dữ liệu của nó. Công cụ sau đó tự thay tiếng Anh bằng tiếng Việt khi trang hiển thị.
| Technical termThuật ngữ kỹ thuật | Plain nameTên dễ hiểu | RoleVai trò |
|---|---|---|
next-intl | The translation engine for the appBộ máy dịch cho ứng dụng | The library that lets a Next.js app show different languages and switch between them by URL (/vi/...)Thư viện giúp ứng dụng Next.js hiển thị nhiều ngôn ngữ và chuyển đổi qua URL (/vi/...) |
namespace | A folder of phrasesMột nhóm chuỗi chữ | We grouped the app's text by area (Home, Suppliers, Pricing...). 16 groups, 1,255 phrases totalChúng tôi nhóm chữ của app theo khu vực (Home, Suppliers, Pricing...). 16 nhóm, tổng 1.255 chuỗi |
parity | Every phrase has both languagesMỗi chuỗi có đủ hai ngôn ngữ | An automatic check (npm run i18n:parity) that fails if any phrase is missing its Vietnamese — this is what guarantees 'no English bleeding through'Một kiểm tra tự động (npm run i18n:parity) báo lỗi nếu chuỗi nào thiếu tiếng Việt — đây là thứ bảo đảm 'không lọt tiếng Anh' |
TranslatePress | The translation tool for WordPressCông cụ dịch cho WordPress | Translates the live site in place (no duplicate pages); stores translations in its own database tableDịch website tại chỗ (không nhân đôi trang); lưu bản dịch trong bảng cơ sở dữ liệu riêng của nó |
dictionary table | The Vietnamese phrasebookCuốn từ điển câu tiếng Việt | A database table pairing each English phrase with its Vietnamese; TranslatePress reads it and swaps text when a page loadsMột bảng dữ liệu ghép mỗi câu tiếng Anh với bản tiếng Việt; TranslatePress đọc nó và thay chữ khi trang tải |
gettext | Theme/plugin button labelsNhãn nút của theme/plugin | A separate small set of UI words (Search, Read More) that WordPress generates in code; handled separately from page contentMột nhóm nhỏ từ giao diện (Search, Read More) do WordPress sinh ra trong code; xử lý riêng so với nội dung trang |
hreflang | The 'this page also exists in Vietnamese' tagThẻ 'trang này cũng có bản tiếng Việt' | An SEO signal telling Google which URL is the EN version and which is the VI version, so they don't competeTín hiệu SEO báo cho Google biết URL nào là bản EN, URL nào là bản VI, để chúng không cạnh tranh nhau |
Read it in 30 seconds: take the normal English page, have WordPress quietly re-render it in Vietnamese so the tool catalogues every phrase, write the curated Vietnamese into the phrasebook, and from then on the tool serves Vietnamese automatically. The whole thing happens privately on the server; visitors never see a half-done site.
Lesson to carry forward: when the front door is locked (can't publish, can't log in a browser), there is often a private server-side door that achieves the same result more safely.
Đọc trong 30 giây: lấy trang tiếng Anh bình thường, cho WordPress lặng lẽ dựng lại bằng tiếng Việt để công cụ liệt kê mọi câu, ghi tiếng Việt đã biên tập vào cuốn từ điển câu, và từ đó công cụ tự phục vụ tiếng Việt. Toàn bộ diễn ra riêng tư trên máy chủ; khách không bao giờ thấy một website dở dang.
Bài học mang theo: khi cửa trước bị khóa (không publish được, không đăng nhập trình duyệt được), thường vẫn có một cửa phía máy chủ riêng tư đạt cùng kết quả mà an toàn hơn.
PipelineQuy trình
What ran, in orderNhững gì đã chạy, theo thứ tự
1
Audit both propertiesRà soát cả hai sản phẩm
Found the fake toggle, the unwired next-intl, and that the WordPress site was English-only by designPhát hiện nút giả, next-intl chưa nối dây, và website WordPress vốn chỉ thiết kế cho tiếng Anh
2
Build the quality systemXây hệ thống chất lượng
Glossary (keep-in-English vs canonical Vietnamese terms), 5 quality gates, and an automatic parity checkerGlossary (từ giữ tiếng Anh vs từ tiếng Việt chuẩn), 5 cổng chất lượng, và bộ kiểm tra parity tự động
3
Wire next-intl into VietConnectNối next-intl vào VietConnect
Moved every route under /[locale], made the header switcher real, rebuilt the middleware to keep login workingĐưa mọi route vào /[locale], làm nút chuyển ở header thành thật, dựng lại middleware để giữ đăng nhập hoạt động
4
Extract & translate the appTrích xuất & dịch ứng dụng
5 agents in parallel pulled out 1,255 phrases across 16 areas; I merged, translated to Vietnamese, and ran the humanizer5 agent chạy song song rút 1.255 chuỗi trên 16 khu vực; tôi gộp lại, dịch sang tiếng Việt và chạy humanizer
5
Verify VietConnectKiểm chứng VietConnect
Build clean, 99 tests pass, 100% parity, /vi pages render Vietnamese end-to-endBuild sạch, 99 test đạt, parity 100%, các trang /vi hiển thị tiếng Việt trọn vẹn
6
Install TranslatePress on TWVCài TranslatePress lên TWV
Set Vietnamese as a draft language at /vi/ (not public); confirmed the live site stayed healthyĐặt tiếng Việt làm ngôn ngữ nháp tại /vi/ (chưa public); xác nhận website thật vẫn khỏe
7
Crack the no-publish pipelineGiải cơ chế dịch không cần publish
Discovered all 4,109 phrases server-side; translated + seeded the homepage; verified 4/4 swapsKhám phá toàn bộ 4.109 chuỗi ở phía máy chủ; dịch + nạp trang chủ; xác nhận 4/4 lần thay đúng
8
Translate the rest of TWVDịch phần còn lại của TWV
~4,064 phrases left (9 pages + 52 articles), in curated batchesCòn ~4.064 chuỗi (9 trang + 52 bài viết), theo từng đợt biên tập
9
Switcher, SEO, publish, QANút chuyển, SEO, publish, QA
Add the header language switcher + hreflang, publish Vietnamese only when complete, then Playwright visual QAThêm nút chuyển ngôn ngữ + hreflang, chỉ publish tiếng Việt khi hoàn tất, rồi QA hình ảnh bằng Playwright
DecisionsQuyết định
Layered decision cardsCác quyết định theo tầng
URL style: keep English clean, only prefix Vietnamese (/vi/)Kiểu URL: giữ tiếng Anh sạch, chỉ thêm tiền tố cho tiếng Việt (/vi/)
L3~35 existing links use bare English URLs; a host redirect (tools.tradewithviet.com) could double-redirect~35 link hiện có dùng URL tiếng Anh trần; một redirect theo host (tools.tradewithviet.com) có thể bị redirect hai lần
L4Always prefix both (/en, /vi) = clean but rewrites every link; or as-needed = English stays bare, only /vi/ addedLuôn thêm tiền tố cả hai (/en, /vi) = gọn nhưng phải sửa mọi link; hoặc as-needed = tiếng Anh giữ trần, chỉ thêm /vi/
L5Least churn that still works — don't rewrite what isn't brokenÍt xáo trộn nhất mà vẫn chạy — đừng sửa thứ chưa hỏng
L6Chose 'as-needed'. Vietnamese pages live at /vi/..., English stays at the normal URL. Same rule used on both properties for consistency.Chọn 'as-needed'. Trang tiếng Việt ở /vi/..., tiếng Anh giữ URL thường. Dùng cùng quy tắc trên cả hai sản phẩm cho nhất quán.
Translate the app with 5 parallel agents writing fragmentsDịch ứng dụng bằng 5 agent song song ghi ra fragment
L3~4,000 phrases is too much to do serially; but agents editing the same two files would collide~4.000 chuỗi quá nhiều để làm tuần tự; nhưng các agent cùng sửa hai tệp sẽ đụng nhau
L4One agent (slow); all agents into one file (collisions); each agent writes its own fragment file, then I mergeMột agent (chậm); mọi agent vào một tệp (đụng độ); mỗi agent ghi tệp fragment riêng, rồi tôi gộp
L5Parallelize, but give each worker its own lane to avoid conflictsSong song hóa, nhưng cho mỗi 'thợ' một làn riêng để tránh xung đột
L6Each agent emitted a fragment; I merged all 16. Caught a bug where some fragments wrapped themselves in their own name (Industries.Industries) and fixed the merge. Recognition signal: when merging machine-made parts, verify the nesting shape before trusting it.Mỗi agent xuất một fragment; tôi gộp cả 16. Bắt được lỗi vài fragment tự bọc trong chính tên mình (Industries.Industries) và sửa khâu gộp. Dấu hiệu nhận biết: khi gộp các phần do máy tạo, hãy kiểm tra hình dạng lồng nhau trước khi tin nó.
Don't publish untranslated Vietnamese — even for 2 minutesKhông publish tiếng Việt chưa dịch — dù chỉ 2 phút
L3The easy way to let the tool 'see' phrases is to publish /vi/ and crawl it; but that exposes a half-English siteCách dễ để công cụ 'thấy' câu chữ là publish /vi/ và quét nó; nhưng việc đó để lộ một website nửa tiếng Anh
L4Briefly publish and crawl (fast but exposes); use the browser editor (needs a password I shouldn't handle); render server-side privatelyPublish ngắn rồi quét (nhanh nhưng để lộ); dùng trình soạn trên trình duyệt (cần mật khẩu tôi không nên xử lý); dựng trang riêng tư ở phía máy chủ
L5The same gate as the app: never expose an incomplete language, not even momentarilyCùng cổng như ứng dụng: không bao giờ để lộ một ngôn ngữ dở dang, dù chỉ thoáng qua
L6The safety classifier blocked the publish-crawl twice — correctly. I found the private server-side render path instead. Recognition signal: a guardrail blocking you is often pointing at a safer path, not just an obstacle.Bộ phân loại an toàn chặn cách publish-rồi-quét hai lần — rất đúng. Thay vào đó tôi tìm ra đường dựng trang riêng tư phía máy chủ. Dấu hiệu nhận biết: một rào chắn chặn bạn thường đang chỉ tới một con đường an toàn hơn, chứ không chỉ là vật cản.
Skip the pitch deck (your call)Bỏ qua bộ pitch deck (theo ý bạn)
L3The investor deck already has its own working EN/VI system, separate from everything elseBộ pitch nhà đầu tư đã có hệ thống EN/VI riêng hoạt động, tách biệt với phần còn lại
L4Fold it into the new system; or leave it on its own; or skip QA for nowGộp vào hệ thống mới; hoặc để nó riêng; hoặc tạm bỏ QA
L5Don't touch what already works and isn't in scopeĐừng động vào thứ đã chạy tốt và không thuộc phạm vi
L6Left the deck on its own system; you asked to skip it for now. It keeps working untouched.Để bộ deck trên hệ thống riêng; bạn yêu cầu tạm bỏ. Nó vẫn chạy nguyên vẹn.
FilesTệp
Artifact mapBản đồ tệp tạo ra
| PathĐường dẫn | WhatLà gì | Who reads itAi dùng |
|---|---|---|
docs/i18n-glossary.md | The bilingual term rulebook — which words stay English, which VietnameseSổ tay thuật ngữ song ngữ — từ nào giữ tiếng Anh, từ nào dịch tiếng Việt | Anyone translating either propertyBất kỳ ai dịch một trong hai sản phẩm |
docs/i18n-quality-gates.md | The 5 checks every Vietnamese string must pass5 kiểm tra mỗi chuỗi tiếng Việt phải qua | Quality control before anything shipsKiểm soát chất lượng trước khi phát hành |
scripts/i18n-parity.ts | Automatic 'no phrase left untranslated' checkerBộ kiểm tra tự động 'không chuỗi nào chưa dịch' | Runs in CI and before every releaseChạy trong CI và trước mỗi lần phát hành |
src/i18n/{routing,request,navigation}.ts | The wiring that makes the app multilingualPhần nối dây giúp ứng dụng đa ngôn ngữ | The Next.js appỨng dụng Next.js |
src/messages/{en,vi}.json | All 1,255 phrases in English and VietnameseToàn bộ 1.255 chuỗi bằng tiếng Anh và tiếng Việt | The translation engine reads theseBộ máy dịch đọc các tệp này |
src/components/layout/header.tsx | The real EN/VI switcher (replaced the fake one)Nút chuyển EN/VI thật (thay nút giả) | Every visitorMọi khách truy cập |
wp_trp_dictionary_en_us_vi_vn (WordPress DB) | The TWV phrasebook — 4,109 phrases, 45 translated so farCuốn từ điển câu của TWV — 4.109 chuỗi, đã dịch 45 | TranslatePress on the live siteTranslatePress trên website thật |
RoadmapLộ trình
What's leftCòn lại những gì
VietConnect is finished. The remaining work is all on the TradeWithViet content site.VietConnect đã xong. Việc còn lại đều ở website nội dung TradeWithViet.
Translate the rest of TWVDịch phần còn lại của TWV
ImpactTác độngHighCaoEffortCông sứcLarge (52 articles)Lớn (52 bài)
~4,064 phrases in curated batches: 9 pages by hand, 52 long articles with AI assistance plus my review on headings and intros.~4.064 chuỗi theo từng đợt biên tập: 9 trang làm tay, 52 bài dài có AI hỗ trợ kèm tôi soát phần tiêu đề và mở đầu.
Switcher + SEO + publishNút chuyển + SEO + publish
ImpactTác độngHighCaoEffortCông sứcMediumVừa
Add the header language switcher and hreflang tags, then publish Vietnamese — only once the whole site is complete and you approve.Thêm nút chuyển ngôn ngữ và thẻ hreflang, rồi publish tiếng Việt — chỉ khi cả website hoàn tất và bạn duyệt.
Visual QAQA hình ảnh
ImpactTác độngMediumVừaEffortCông sứcSmallNhỏ
Check the Vietnamese pages in a real browser (Playwright) so no layout breaks and nothing mixes languages.Kiểm tra các trang tiếng Việt trong trình duyệt thật (Playwright) để không vỡ layout và không trộn ngôn ngữ.
Nothing here is public yet. The Vietnamese site stays hidden until it is complete and you say go.Chưa có gì ở đây là public. Website tiếng Việt vẫn ẩn cho tới khi hoàn tất và bạn cho phép.
Your actions (optional / when ready)Việc của bạn (tùy chọn / khi sẵn sàng)
- VietConnect: to turn the Vietnamese toggle ON, set NEXT_PUBLIC_ENABLE_VI=true (in .env.local locally, or in Vercel for production). It's intentionally off until you're ready.VietConnect: để BẬT nút tiếng Việt, đặt NEXT_PUBLIC_ENABLE_VI=true (trong .env.local ở máy, hoặc trong Vercel cho production). Hiện cố ý để tắt cho tới khi bạn sẵn sàng.
- Review/commit the VietConnect changes — they're in your working tree, nothing committed yet.Xem lại/commit các thay đổi VietConnect — chúng đang ở working tree, chưa commit gì.
- TWV app password: I'll tell you when I no longer need it; you can delete it any time at tradewithviet.com/wp-admin/profile.php.App password của TWV: tôi sẽ báo khi không cần nữa; bạn có thể xóa bất cứ lúc nào tại tradewithviet.com/wp-admin/profile.php.
- TWV publish: I will NOT publish the Vietnamese site until it's fully translated and you approve.Publish TWV: tôi sẽ KHÔNG publish website tiếng Việt cho tới khi dịch xong hoàn toàn và bạn duyệt.
Self-testTự kiểm tra
Check your understandingKiểm tra mức hiểu của bạn
Why is the Vietnamese toggle kept hidden until translation is 100% complete?Vì sao nút tiếng Việt được giữ ẩn cho tới khi dịch xong 100%?
Why translate the WordPress site by rendering it server-side instead of publishing /vi/ and crawling it?Vì sao dịch website WordPress bằng cách dựng trang phía máy chủ thay vì publish /vi/ rồi quét?
In your own words: what does the 'parity check' guarantee, and why does it matter for your brand?Bằng lời của bạn: 'kiểm tra parity' bảo đảm điều gì, và vì sao nó quan trọng cho thương hiệu?
Mastery checklist — tick what you can explain unpromptedBảng tự đánh giá — tích những gì bạn tự giải thích được