Skip to content

translation: add AI sync contract and refresh zh-TW / kor#2133

Open
tigercosmos wants to merge 3 commits intoseladb:masterfrom
tigercosmos:ai_translation
Open

translation: add AI sync contract and refresh zh-TW / kor#2133
tigercosmos wants to merge 3 commits intoseladb:masterfrom
tigercosmos:ai_translation

Conversation

@tigercosmos
Copy link
Copy Markdown
Collaborator

@tigercosmos tigercosmos commented May 8, 2026 •
edited
Loading

Summary

  • Add translation/ai_translation_prompt.md — a contract any AI agent (Claude, Codex, Gemini, GPT, etc.) follows to verify and sync the translated READMEs against the canonical English README.md. Defines triggers, a structural verification matrix, faithful github-slugger anchor rules, badge alt-text and HTML-embed policies, and a mandatory "synced using AI" caution at the top of every translated file.
  • Refresh translation/README-zh-tw.md to be 1:1 with the current English README.md: missing protocols added (Cisco HDLC at L2 Fix the extra space created in platform.mk after running configure-windows.bat #1 plus the 5 L7 entries already in upstream — Cryptographic key decoders, DoIP, Modbus, PEM, X509 — and the 2 newly upstreamed L7 entries MySQL how to catch htttp cmd with the hls protocol #47 and PostgreSQL Wire Protocol (PGWire) EthLayer.setSoureMac() has typo in method name #50), broken TOC anchors fixed, L6 heading aligned with its anchor, vcpkg/conan code-fence info strings corrected, WinDivert link added in the intro / Feature Overview / Pcap++ engine list, AI-sync caution added.
  • Refresh translation/README-kor.md to be 1:1 with the current English README.md: same protocol additions and renumbering (final total 58), missing TLS Fingerprinting Feature Overview bullet restored, Packet reassembly bullet expanded to full English prose, missing API-doc "contact us" sentence restored, raw <picture>/<source>/<img> Multi-Platform Support embeds restored, DPDK/PF_RING and Benchmarks sections split back into their English paragraph structure, TOC/heading anchors fixed, WinDivert added, AI-sync caution added.

Commits

  1. 186f5e1f — initial AI sync contract + first refresh of zh-TW / kor.
  2. d62bc50c — sync zh-TW / kor with new upstream README content (WinDivert, MySQL, PGWire) after rebasing onto upstream/master.
  3. 27ca0790 — address Codex review: rewrite the contract's anchor-slug rules to faithfully describe github-slugger, clarify the "synced using AI" caution format, and restore prose-level 1:1 sync in the Korean file (placeholder, Packet reassembly, API-doc anchor, Multi-Platform HTML embeds, DPDK/PF_RING split, Benchmarks split).

Test plan

  • Open both translated READMEs on GitHub and confirm every TOC link jumps to the matching heading in the same file.
  • Verify each translated file has 58 numbered protocol entries matching the English file 1:1.
  • Verify the "synced using AI" caution renders as a warning blockquote at the very top of each translated file.
  • Verify the Korean Multi-Platform Support section renders the 5 OS logo <picture> blocks (Windows, Linux, MacOS, Android, FreeBSD), matching English.
  • Verify the English README.md is unchanged on this branch.

🤖 Generated with Claude Code

@tigercosmos tigercosmos requested a review from seladb as a code owner May 8, 2026 18:36
tigercosmos
tigercosmos commented May 8, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inline annotations on the key parts of this change. The PR body has the high-level summary; these comments call out the why on individual diff hunks so reviewers can audit each fix in context.

Comment thread translation/ai_translation_prompt.md
2. The file contains a `Translations:` line that lists the same set of sibling files as the English source.
- If new `translation/README-*.md` files are added in the future, they automatically fall under this instruction and must be checked the same way. Adding a new translation requires updating the `Translations:` line in **every** existing README (English and all sibling translations) in the same change.

### 1.1 Mandatory "Synced using AI" caution
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 1.1 is the contract's only sanctioned translation-only addition: every translated file must open with a localized "synced using AI" caution. The reference snippets below pin canonical wording for zh-TW and Korean so future agents don't drift. Section 4 (line 183) is reconciled to permit this exception.

tigercosmos and others added 2 commits May 8, 2026 20:42
@tigercosmos @claude
translation: add AI sync contract and refresh zh-TW / kor
186f5e1 
- Add translation/ai_translation_prompt.md: a contract any AI agent
  (Claude, Codex, Gemini, GPT, etc.) follows to verify and sync the
  translated READMEs against the canonical English README. Defines
  triggers, a structural verification matrix, GitHub anchor-slug
  rules, badge alt-text and HTML-embed policies, and a mandatory
  "synced using AI" caution that must appear at the top of every
  translated file.

- Refresh translation/README-zh-tw.md to match the current English
  README: add Cisco HDLC at L2 #1 and renumber L2-L7 (50 -> 56
  protocols); add 5 missing L7 entries (Cryptographic key decoders,
  DoIP, Modbus, PEM, X509); fix broken TOC anchors and Homebrew
  case; localize stale inline anchors (#download, #provide-feedback);
  align L6 heading text with the TOC; correct code-fence info strings
  for vcpkg/conan blocks; add the "synced using AI" caution at top.

- Refresh translation/README-kor.md to match the current English
  README: add Cisco HDLC and the 5 missing L7 entries; renumber
  L2-L7; add the missing TLS Fingerprinting bullet to Feature
  Overview; fix TOC anchors and section/heading mismatches
  (#download, 라이센스, 기여, 성능 벤치마크); add the "synced using
  AI" caution at top.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@tigercosmos @claude
translation: sync zh-TW / kor with new upstream README content
d62bc50 
After rebasing onto upstream/master, propagate the changes that
landed in README.md:

- Add WinDivert link in the intro paragraph, the Feature Overview
  "Packet capture" bullet, and the API Documentation Pcap++ engine
  list (also adds AF_XDP to the Pcap++ list).
- Add the two new L7 protocol entries (MySQL seladb#47, PostgreSQL Wire
  Protocol (PGWire) seladb#50) and renumber L7 from 47 onward, taking the
  protocol list from 56 to 58 entries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tigercosmos
tigercosmos commented May 8, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rebased onto current upstream/master and synced the two new pieces of upstream README content: the WinDivert engine (added in #2019) and two new L7 protocols — MySQL (#2103) and PostgreSQL Wire Protocol / PGWire (#2070). Inline notes flag each touch-point so reviewers can audit per-language consistency.

@tigercosmos
Copy link
Copy Markdown
Collaborator Author

tigercosmos commented May 8, 2026 •
edited
Loading

@seladb per discussion before, here is the AI-generated translation prompt with outputs. Please take a look. cc @clementperon @Dimi1010 @egecetin

@tigercosmos @claude
translation: address Codex review — fix kor 1:1 sync and prompt slug …
27ca079 
…rules

Contract (translation/ai_translation_prompt.md):
- Anchor handling: rewrite the GitHub slug rules to faithfully describe
  github-slugger's algorithm — per-character whitespace replacement
  (not per-run), case folding via toLowerCase that also affects
  accented Latin, explicit punctuation-stripping notes for CJK, and a
  worked-examples table covering A&B, multi-space, accented Latin,
  CJK, and existing TW/Korean headings.
- Section 1.1 caution format: clarify that the bold lead-in is a
  localized label (注意：/참고:/Note:) and the AI mention sits in the
  prose, not inside the bold span — matching the canonical reference
  snippets and the existing translated files.

translation/README-kor.md (1:1 sync gaps Codex flagged):
- Restore <path-to-package-file> placeholder in the gh attestation
  shell command (was wrongly localized).
- Expand the Packet reassembly Feature Overview bullet to fully cover
  TCP retransmission, out-of-order, missing data, and IPv4/IPv6
  fragment creation/reassembly (was abridged to one phrase).
- Restore the missing "If you see any missing data please contact us"
  sentence under API Documentation, with the localized #피드백-제공
  same-file anchor.
- Restore the raw <picture>/<source>/<img> Multi Platform Support
  block matching the English HTML structure (was collapsed to a
  single sentence with no embeds).
- Split the DPDK And PF_RING Support section back into its 4 English
  paragraphs and reinstate the "routers, firewalls, load balancers"
  and boilerplate-removal details that had been collapsed away.
- Split the Benchmarks section back into 2 paragraphs to match
  English structure.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tigercosmos
tigercosmos commented May 8, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up addressing the Codex review: tightens the slug-rule contract to actually match github-slugger and restores prose-level 1:1 sync in the Korean file (placeholder, Packet reassembly bullet, API-doc contact-us sentence, Multi-Platform HTML embeds, DPDK/PF_RING split, Benchmarks split).

Comment thread translation/ai_translation_prompt.md

The algorithm, in order:

1. **Lowercase via `String.prototype.toLowerCase()`** — this lowercases ASCII Latin **and** accented Latin (so `É` → `é`). CJK, Hangul, Hiragana, Katakana, Cyrillic without case, etc. are preserved unchanged.
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Anchor handling rewritten to faithfully describe github-slugger. Key corrections: lowercasing via String.prototype.toLowerCase() also case-folds accented Latin (É → é); whitespace is replaced per-character (so A B → a---b), not per-run; existing - runs are preserved untouched.

Comment thread translation/README-kor.md
PcapPlusPlus는 현재 __Windows__, __Linux__, __MacOS__, __Android__, __FreeBSD__에서 지원됩니다. PcapPlusPlus 웹사이트에서 [지원 플랫폼](https://pcapplusplus.github.io/docs/platforms) 전체 목록을 확인할 수 있으며, [다운로드](#download) 섹션을 참조하여 해당 플랫폼에서 PcapPlusPlus를 시작하세요.
PcapPlusPlus는 현재
__Windows__
<picture>
Copy link
Copy Markdown
Collaborator Author

@tigercosmos tigercosmos May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restored the raw <picture>/<source>/<img> Multi Platform Support block. The previous version collapsed all 5 OS-logo embeds into a single prose sentence, which violated the HTML-embeds verification row in the contract — every <picture>/<img> must mirror the English structure with byte-identical non-prose attributes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@seladb seladb Awaiting requested review from seladb seladb is a code owner

@clementperon clementperon Awaiting requested review from clementperon

@Dimi1010 Dimi1010 Awaiting requested review from Dimi1010

@egecetin egecetin Awaiting requested review from egecetin

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tigercosmos