CI on Go 1.27, and a content switch so the inherited tests can run

.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: ci
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  # The Go the site is built and tested with. go.mod stays on upstream's
+  # version on purpose: it is a minimum language version, changing it in the
+  # fork puts a seventh file into the divergence and makes every upstream sync
+  # conflict on go.mod, and it says nothing about what CI runs. This does.
+  GO_VERSION: '1.27.0'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-go@v7
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache: true
+
+      - name: vet
+        run: go vet ./...
+
+      - name: build
+        run: go build ./...
+
+      # GODEV_CONTENT=en turns the Vietnamese overlay off.
+      #
+      # This suite is upstream's and it asserts English strings: cmd/golangorg
+      # checks that every release notes page carries its release date, and
+      # internal/tour checks for `>A Tour of Go<`. Neither goes through the
+      # server's -content flag, so with the overlay on they get Vietnamese and
+      # fail, and they are not wrong to. What they are testing is the renderer,
+      # and the fork has to not break the renderer.
+      #
+      # Whether the translation is any good is a different question with a
+      # different answer, and that is the audit job below.
+      #
+      # cmd/screentest is excluded because it dials Google Cloud Storage for
+      # screenshot baselines and cannot pass without credentials. That is true
+      # upstream too.
+      - name: test
+        env:
+          GODEV_CONTENT: en
+        run: go test $(go list ./... | grep -v /cmd/screentest)
+
+      # The overlay is the fork, so it is tested with the overlay on.
+      - name: test the overlay
+        run: go test -run 'TestOverlay|TestGODEVCONTENT' -v .
+
+  # The quality gates, from tamnd/godev-vn-translator, run against this
+  # checkout. Fourteen deterministic rules over every English and Vietnamese
+  # pair: dropped links, invented heading anchors, edited code blocks,
+  # translated template actions, front matter that moved, and whether each
+  # translation still matches the English it was made from.
+  #
+  # -max is a ratchet and not a target. The corpus has 227 refusals today, so a
+  # gate demanding zero would be red on every pull request including the ones
+  # fixing it, and a check that is always red is a check somebody turns off.
+  # This one fails at 228. The number comes down in the same diff as the work
+  # that lowers it, which makes it a reviewable claim, and the day it reaches
+  # zero the flag comes off.
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: godev-vn
+      - uses: actions/checkout@v7
+        with:
+          repository: tamnd/godev-vn-translator
+          path: translator
+      - uses: actions/setup-go@v7
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: translator/go.sum
+
+      - name: audit
+        working-directory: translator
+        run: go run ./cmd/godev -C ../godev-vn audit -max 227
+
+      # No -max here on purpose. This step runs even when the gate above failed,
+      # which is exactly when the report is worth reading, so it must not fail
+      # for the same reason twice.
+      - name: write the report
+        if: always()
+        working-directory: translator
+        run: go run ./cmd/godev -C ../godev-vn audit -quiet -report audit.md
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: audit
+          path: godev-vn/audit.md

.gitignore

@@ -0,0 +1,7 @@
+# Upstream has no .gitignore, so this file is the fork's and it is short on
+# purpose. Only things this fork's own tooling drops into the tree.
+
+# The audit report, written by `godev audit -report` and uploaded by CI.
+audit.md
+
+.DS_Store

AGENT.md

@@ -0,0 +1,87 @@
+# Agent guidelines
+
+This is `tamnd/godev-vn`, a fork of `golang/website` that serves go.dev in Vietnamese.
+
+## Pull requests
+
+Open them on this repository, never on upstream:
+
+```
+gh pr create --repo tamnd/godev-vn
+```
+
+Upstream is `golang/website` and it is a fetch remote for syncing. Nothing here goes back to it except a change that is correct for upstream on its own merits, and that is a separate deliberate pull request rather than something that happens by accident.
+
+## How the two languages fit together
+
+English lives in `_content` and Vietnamese in `_content_vi`. `content.go` overlays the second on the first:
+
+```go
+func (o *overlayFS) Open(name string) (fs.File, error) {
+	f, err := o.overlay.Open(name)
+	if err == nil {
+		return f, nil
+	}
+	return o.base.Open(name)
+}
+```
+
+A file missing from `_content_vi` is served from `_content`, so the site always renders. That is right for a reader and it is the thing to keep in mind while working here, because it has three consequences:
+
+- A missing translation is invisible. The page renders in English and returns 200.
+- A wrong translation is invisible in the same way, since there is no error to raise.
+- Browsing the site tells you nothing about coverage, because a page that was never translated looks exactly like a finished page that is meant to be in English.
+
+So do not judge the state of this repository by looking at it in a browser. Run the audit.
+
+## The audit is the source of truth
+
+The tooling lives in `tamnd/godev-vn-translator`, checked out beside this repository.
+
+```
+$ cd ../godev-vn-translator
+$ go run ./cmd/godev audit ../godev-vn
+```
+
+It reports coverage, runs fourteen deterministic gates over every English and Vietnamese pair, and exits non-zero when anything is refused. Notices never fail it.
+
+Run it before opening a pull request that touches `_content_vi`. A change that adds a refusal is a change that should not merge.
+
+`TRANSLATE.md` is a frozen snapshot from March 2026 and its counts no longer match the tree. Prefer the audit.
+
+## `translations.json`
+
+At the root, recording for each translation the SHA-256 of the English it was made from, the hash of the instructions used, which route and model answered, and how many pieces the file went over in.
+
+Do not hand edit it and do not regenerate it against the current English. Its whole value is that it says what a translation was made from, which is how a sync that moves the English can be told from one that did not. A record rewritten to match today's English answers no question at all.
+
+## `GLOSSARY.md`
+
+The agreed rendering for terms that keep coming up. It is a Markdown table so that a person can open it, disagree with a row, and change it.
+
+Some terms deliberately keep the English word: `commit`, `repository`, `workspace`, `generics`, `dependency`. A Go programmer reading Vietnamese says those in English, and rendering them into Vietnamese is not more Vietnamese, it is less readable. When the Vietnamese column repeats the English word, that is the instruction.
+
+Adding a row takes effect immediately. The glossary is read off disk at run time and is deliberately not part of the prompt hash, so a new term does not put the whole corpus back in the queue.
+
+## Things that are structure and not prose
+
+These are what the gates check, and they are the mistakes that get made:
+
+- A link target is copied character for character. The bracket text and any quoted title are prose.
+- A heading's `{#id}` is copied exactly. A heading that loses one gets a new anchor made from its Vietnamese words, and every link into that section breaks while the page still renders.
+- Inside a fenced block, only the comments are prose.
+- Everything between `{{` and `}}` is code the site runs.
+- Front matter keys stay in the same order, and `date`, `by`, `tags`, `layout`, `template`, `redirect` and `series` are copied as data. Never add `template: true` to a Vietnamese page whose English does not have it.
+- Never put a backslash in front of Markdown punctuation. `\-` is not a bullet and `\#` is not a heading.
+
+## Syncing with upstream
+
+```
+git fetch upstream
+git checkout -b sync/upstream-NNNN
+git merge upstream/master
+```
+
+The fork diverges from upstream in six files: `AGENT.md`, `GLOSSARY.md`, `INDEX.md`, `TRANSLATE.md`, `content.go` and `cmd/golangorg/server.go`. The first four are new, so only the last two can conflict, and both are the overlay wiring.
+
+Afterwards, run the audit. The L13 refusals are the list of translations the sync just invalidated, by name.

GLOSSARY.md

@@ -0,0 +1,69 @@
+# Translation Glossary
+
+Tệp này xác định các bản dịch tiếng Việt ưu tiên và các quyết định văn phong cho
+`_content_vi/`.
+
+Cập nhật bảng thuật ngữ này trong quá trình dịch:
+
+- Thêm thuật ngữ khi một cụm từ lặp lại nhiều lần hoặc mang tính chuyên ngành.
+- Ưu tiên một bản dịch thống nhất cho mỗi khái niệm, trừ khi ngữ cảnh đòi hỏi khác đi.
+- Giữ nguyên tên sản phẩm, tên kho lưu trữ, tên tệp và cú pháp truy vấn.
+- Giữ nguyên mã nguồn, URL và các đoạn lệnh.
+- Khi chủ ý giữ nguyên một thuật ngữ không dịch, hãy ghi rõ quyết định đó tại đây.
+
+## Quy ước
+
+- Văn phong: rõ ràng, kỹ thuật, trung tính.
+- Tên sản phẩm: `Go`
+- Tên dự án: `dự án Go`
+- Lịch sử quản lý mã nguồn: `lịch sử quản lý mã nguồn`
+- Tác giả: `tác giả`
+- Commit: `commit`
+- Thay đổi: `thay đổi`
+- Tìm kiếm: `tìm kiếm`
+- Chuyển hướng: `chuyển hướng`
+- Máy chủ: `máy chủ`
+- Nguồn tham chiếu chính: `nguồn thông tin chính xác nhất`
+
+## Thuật ngữ đã chốt
+
+| Thuật ngữ gốc | Bản dịch ưu tiên | Ghi chú |
+| --- | --- | --- |
+| Authors of Go | Tác giả của Go | Page title in `_content_vi/AUTHORS.md`. |
+| Go project | dự án Go | Keep `Go` untranslated. |
+| AUTHORS | AUTHORS | Filename, do not translate. |
+| CONTRIBUTORS | CONTRIBUTORS | Filename, do not translate. |
+| author | tác giả | Use for people credited for commits or changes. |
+| contributor | contributor | Keep unchanged — do not translate. |
+| commit | commit | Keep the Git term unchanged. |
+| repository | repository | Keep unchanged — do not translate. |
+| source control history | lịch sử quản lý mã nguồn | Prefer this over shorter paraphrases. |
+| authoritative source | nguồn thông tin chính xác nhất | Matches current translation. |
+| Go's Gerrit instance | máy chủ Gerrit của Go | Keep `Gerrit` as a product name. |
+| search for changes | tìm kiếm các thay đổi | General action phrase. |
+| redirect | chuyển hướng | For front matter semantics and prose. |
+| ecosystem | hệ sinh thái | Prefer this in Go platform context. |
+| community | cộng đồng | General community term. |
+| open-source | mã nguồn mở | Use in general prose. |
+| anniversary | kỷ niệm | Use for anniversary or milestone context. |
+| birthday | sinh nhật | Use for celebratory wording. |
+| cloud software | phần mềm đám mây | Prefer this in infra context. |
+| garbage collector | bộ gom rác | Preferred runtime term. |
+| tooling | hệ thống công cụ | Use for developer-tooling context. |
+| release | bản phát hành | Use for product or language releases. |
+| vulnerability | lỗ hổng bảo mật | Security context. |
+| dependency | dependency | Keep this term in technical prose when clearer. |
+| generics | generics | Keep the feature name unchanged for now. |
+| production-ready | sẵn sàng cho môi trường production | Preferred phrase in release notes. |
+| editor-neutral | trung lập với trình soạn thảo | For tooling compatibility context. |
+| workspace | workspace | Keep unchanged in Go feature naming. |
+| soft memory limit | giới hạn bộ nhớ mềm | Runtime and GC context. |
+| supply chain security | bảo mật chuỗi cung ứng | Security context. |
+| false positive | dương tính giả | Security and tooling context. |
+| structured logging | structured logging | Keep unchanged for now. |
+| profile-guided optimization | tối ưu hóa dựa trên hồ sơ thực thi | Compiler and performance context. |
+
+## Quyết định đang áp dụng
+
+- Dùng tiếng Việt có dấu nhất quán trong toàn bộ `_content_vi/`.
+- Ưu tiên cách diễn đạt tự nhiên trong tiếng Việt thay vì bám sát từng từ tiếng Anh.