add translation-review-comment skill and doc review workflow

- skills/translation-review-comment/SKILL.md: 14 rules distilled from 473 Wade editor comments across 3 manuscripts - translate-files/佛法与企业管理/review-comments.dj: manual comment reference for maple's translation (anchored comments not possible via API) - docs/google-docs-comment-journey.dj: full journey log from OAuth setup to discovering Google Drive API's anchor limitation
2026-06-21 10:13:32 +08:00
parent fe603f15fc
commit 71eccff31c
10 changed files with 1008 additions and 18 deletions
@@ -0,0 +1,133 @@
+# Google Docs Comment Automation — Journey Log
+
+2026-06-21
+
+## Background
+
+Task: review Chinese→English Buddhist translation manuscripts on Google Docs
+by adding editorial comments (the "Wade" style — anchored suggestions on
+specific text). The reviewer is an AI agent running on Hermes with API access.
+
+## Phase 1: Google Workspace OAuth Setup
+
+Set up OAuth2 for Google Workspace access:
+- Created Google Cloud project (932146571366)
+- Enabled APIs: Gmail, Calendar, Drive, Sheets, Docs, People
+- Created Desktop OAuth client, downloaded client_secret.json
+- Completed OAuth PKCE flow → token at ~/.hermes/google_token.json
+
+Success: authenticated with scopes covering all needed services.
+
+## Phase 2: Reading Documents and Comments (Success)
+
+Used the Google Drive API v3 `comments.list` endpoint to fetch comments
+from existing review documents:
+
+- Doc 1 (1DTzH7...): 61 人生佛教在当代的弘扬 — 121 comments
+- Doc 2 (13S_0u...): 附录 我的判教观 — 151 comments
+- Doc 3 (1LxCcX...): 16 觉醒的艺术 — 201 comments
+
+Total: 473 editor comments by Wade, spanning 2026-04-17 to 2026-06-20.
+These comments were well-anchored (kix.XXXXXXXX format) and contained
+actionable editorial suggestions in Chinese.
+
+## Phase 3: Pattern Analysis (Success)
+
+Analyzed all 473 comments to extract systematic review rules. The editor's
+feedback follows clear patterns:
+
+R1  — Active voice + "we" subject
+R2  — Noun → verb conversion
+R3  — Simplify vocabulary
+R4  — Break long sentences
+R5  — Remove unnecessary words
+R6  — Conversational / interview tone
+R7  — No -ly adverbs
+R8  — Concrete over abstract
+R9  — Terminology alignment
+R10 — Missing content detection
+R11 — Source faithfulness
+R12 — Sentence structure clarity
+R13 — Specific word fixes
+R14 — Positive feedback (随喜), naming the translator
+
+Created skill: skills/translation-review-comment/SKILL.md
+
+## Phase 4: Attempting to Create Anchored Comments (Failure)
+
+Task: apply the review rules to a new document
+(1NmJKNavB4IBg56ZRBdS5ux9ObRVlHPnSxVmjjXCyITs — 佛法与企业管理, translator: maple).
+
+### Attempt 1: comments.create without anchor
+
+Result: comments appear as document-level (unanchored). The translator has no
+way to know which text each comment refers to. User rejected this approach:
+"Without anchors, there is no way to know where the translator should edit."
+
+### Attempt 2: kix anchors from Docs API response
+
+Searched the document body via `documents.get` for kix segment IDs.
+Result: the Docs API response does NOT expose kix anchors. Only footer IDs
+(kix.hf0, kix.list) appear. Text segments have no kix identifiers.
+
+### Attempt 3: kix anchors from HTML export
+
+Exported the document as HTML via Drive API `files.export_media`.
+Result: HTML export contains NO kix IDs. Since 2021, Google Docs renders
+content on `<canvas>`, so there are no DOM nodes with kix attributes in
+the exported HTML.
+
+### Attempt 4: Browser-based kix extraction
+
+Tried navigating to the document via browser to extract kix IDs from the
+live page DOM. Result: requires Google sign-in. Agent cannot authenticate
+to Google in a browser session.
+
+### Attempt 5: Line-based anchor format (official docs)
+
+The Drive API docs describe an alternative anchor format using line numbers:
+```json
+{"region": {"kind": "drive#commentRegion", "line": 1, "rev": "head"}}
+```
+Created a test comment with this format. Pending user verification on whether
+it actually anchors in the Google Docs UI.
+
+### Official Position
+
+The Google Drive API documentation states (as of 2025):
+
+> "The anchor is saved and returned when retrieving the comment, however
+> Google Workspace editor apps treat these comments as un-anchored comments."
+
+The kix.* anchor format is Google's internal, undocumented format that has
+never been reverse-engineered. A 2016 thread on the Google Apps Script
+community confirms this has been a known limitation for nearly a decade
+with no resolution.
+
+## Phase 5: Workaround
+
+Created `translate-files/佛法与企业管理/review-comments.dj` — a structured
+file listing each comment with:
+- The specific text it should anchor to (quoted)
+- The comment content
+
+The translator can manually add these comments in the Google Docs UI by
+selecting the quoted text and inserting each comment.
+
+## Key Findings
+
+1. **Reading comments works perfectly** via Drive API `comments.list`
+2. **Writing anchored comments does NOT work** — the anchor is silently
+   ignored by Google Docs editor apps
+3. **The only reliable way** to add anchored comments to Google Docs is
+   through the browser UI (select text → Insert → Comment), which requires
+   human interaction or a headless browser with Google authentication
+4. **Google Apps Script** might support anchored comments from within
+   the document environment (untested — requires different auth model)
+5. The `translation-review-comment` skill remains useful for `.dj` file
+   review where `patch` can be used instead of comments
+
+## Files Created
+
+- skills/translation-review-comment/SKILL.md — systematic review rule checklist
+- translate-files/佛法与企业管理/review-comments.dj — manual comment reference
@@ -0,0 +1 @@
+,user,17,20.06.2026 22:13,file:///home/user/.config/libreoffice/4;
@@ -0,0 +1 @@
+,user,17,20.06.2026 22:14,file:///home/user/.config/libreoffice/4;
@@ -0,0 +1,425 @@
+---
+name: translation-review-comment
+description: Editorial polish pass for CN→EN Buddhist translation — voice, flow, readability. Applies patterns distilled from 473 editor comments across 3 manuscripts. Use AFTER translation-review for terminology/accuracy checks.
+---
+
+# Translation Review — Comment (Editorial Polish)
+
+Editorial polish for CN→EN Buddhist translation manuscripts. Focuses on voice, flow,
+and readability — the layer beyond terminology and accuracy. Distilled from 473
+editor comments by Wade across 3 manuscripts:
+
+| Document | Comments | Period |
+|----------|----------|--------|
+| 61 人生佛教在当代的弘扬 | 121 | 2026-06-19–20 |
+| 附录 我的判教观 | 151 | 2026-06-13–16 |
+| 16 觉醒的艺术 | 201 | 2026-04-17–05-24 |
+
+## When to Use
+
+After `translation-review` (terminology, accuracy, line parity). This skill targets the
+"Pass 3" layer — does the English read as natural prose, or as translationese?
+
+Apply to `.dj` files with `patch` or to Google Docs comment threads.
+
+## Core Principles
+
+Three principles drive all the specific rules below:
+
+1. **Reader engagement** — the English should invite the reader in. Use "we," active
+   voice, conversational tone. The original is an interview/dialogue; the translation
+   should sound like one.
+2. **Simplicity over sophistication** — prefer everyday words over academic ones.
+   If a construction feels heavy, stiff, or formal, simplify it.
+3. **Source faithfulness** — never add content not in the Chinese, and never drop
+   content that is. But restructure freely for natural English flow — don't mirror
+   Chinese word order when it produces awkward English.
+
+## Rule Checklist
+
+Apply these in order. Each rule includes the signal (what to look for) and the fix
+pattern. Examples are drawn from actual editor comments.
+
+---
+
+### R1: Active Voice + "We" Subject
+
+**Signal**: Passive voice, impersonal "one," "it," abstract subjects.
+
+**Fix**: Use "we" or a concrete human subject.
+
+```
+- "the propagation of Buddhism must move toward modernisation"
+ "we must bring Buddhism into the modern age"
+
+- "it becomes even harder to have an environment for further study"
+ "students find it even harder to have a place for further study"
+
+- "One must further develop the mind of renunciation"
+ "We must further develop the mind of renunciation"
+```
+
+**Check**: Scan for "one" (as pronoun), passive "be + past-participle," and sentences
+where the subject is an abstract noun phrase. Replace with "we" + active verb.
+
+---
+
+### R2: Noun → Verb Conversion
+
+**Signal**: Heavy noun phrases where a verb would be lighter and clearer.
+Especially common with: propagation, promotion, engagement, commercialisation,
+modernisation, adjustment, continuation, cultivation, development.
+
+**Fix**: Replace the noun with its verb form. Restructure the sentence around a
+human subject (usually "we").
+
+```
+- "the adjustment of focus in"          → delete entirely or rephrase
+- "for the propagation of the Dharma"   → "to spread the Dharma"
+- "the promotion of Humanistic Buddhism" → "as we actively promote..."
+- "engagement with the worldly realm"   → "it engages with worldly affairs"
+- "commercialisation"                   → "society has become increasingly commercialized"
+- "the continuation of"                 → "flow"
+```
+
+**Check**: Search for `tion of`, `ment of`, `isation of`. Try deleting the phrase
+first — often the sentence flows fine without it.
+
+---
+
+### R3: Simplify Vocabulary
+
+**Signal**: Formal, academic, or literary words that an everyday reader would trip on.
+
+**Fix**: Replace with the simplest word that preserves the meaning.
+
+```
+Academic → Everyday:
+  "provisions" (资粮)       → "spiritual resources" or rephrase
+  "constitutes"             → "is" / "forms" / "makes up"
+  "cognizes"                → "understands"
+  "transient"               → "changing" / "impermanent"
+  "ancestral masters"       → "great masters"
+  "eminent monks and great masters" → pick one (redundant)
+  "mode of existence"       → "way of living"
+  "the degree of this entrapment" → "how tightly we cling"
+  "corresponding"           → "proper" / "solid" or delete
+  "uncritically"            → delete (accepting covers it)
+  "sublimated"              → simpler word
+  "encompassing"            → simpler word
+  "inherently unsustainable" → "they will not last"
+```
+
+**Check**: For each sentence, ask: would I say this word in conversation? If not,
+find the everyday equivalent.
+
+---
+
+### R4: Break Long Sentences
+
+**Signal**: Single sentence with 3+ clauses, especially with lists, parallel
+structures, or multiple "and"/"while"/"with" connectors.
+
+**Fix**: Split into 2–3 shorter sentences. Each sentence should convey one idea.
+
+```
+Before (one sentence):
+  "Influenced by society, many within the Buddhist community have also become
+   enthusiastic about power and economic gain, treating tourism and ritual services
+   as the main focus programme of temples, while neglecting their proper
+   responsibility of carrying on the Buddha's mission."
+
+After (two sentences):
+  "Influenced by society, some in the Buddhist community have also become
+   enthusiastic about power and money. They make tourism and ritual services the
+   main focus of temple activities, while neglecting their true duty to carry on
+   the Buddha's mission."
+```
+
+**Check**: Count clauses. If >2, consider splitting. Especially split:
+- When a list starts mid-sentence
+- When "while" / "with" introduces a new subject
+- When a long parenthetical could stand alone
+
+---
+
+### R5: Remove Unnecessary Words
+
+**Signal**: Modifiers that don't add meaning, filler words, redundant pairs.
+
+**Fix**: Delete them. The sentence should stand without them.
+
+```
+Common deletions:
+  "so-called"         — almost always deletable
+  "generally"         — deletable unless making a specific contrast
+  "phenomenon"        — "this phenomenon" → "this"
+  "fundamentally"     — deletable
+  "necessarily"       — deletable
+  "solely"            — deletable
+  "briefly summarise" — "briefly" is redundant with "summarise"
+  "and influenced"    — deletable
+  "the practice of"   — often deletable
+  "The development of"— often deletable
+  "and investigating" — if already "studying," drop
+  "practical" (in "practical methods") — "methods" alone covers it
+```
+
+**Check**: For each word: does removing it change the meaning? If not, remove it.
+
+---
+
+### R6: Conversational / Interview Tone
+
+**Signal**: Formal register, stiff constructions, academic phrasing in a dialogue
+context. The Chinese originals are interviews; the English should read as spoken word.
+
+**Fix**: Imagine you're saying it aloud. Adjust accordingly.
+
+```
+Formal                            → Conversational:
+  "What do you think is the       → "Why do you think that is?"
+   reason for this?"
+  "outdated"                      → "old-fashioned" (in spoken context)
+  "It is summarised in the        → Use direct speech
+   famous expression: ..."
+  "the common point of the        → "what all these issues have
+   above-mentioned issues"            in common"
+  "From the perspective of        → "Looking at Buddhist history,"
+   Buddhist history,"
+  "besides remaining grounded     → "In the modernisation of Buddhism,
+   in the principle of adapting        while we must stay true to..."
+   both to Buddhist teachings
+   and to the needs of the people"
+```
+
+**Check**: Read the passage aloud (mentally). Does it flow like speech? If it feels
+like a lecture transcript, lighten it.
+
+---
+
+### R7: No -ly Adverbs
+
+**Signal**: Adverbs ending in -ly.
+
+**Fix**: Delete them, or restructure to avoid them. Modern English style avoids
+adverb clutter.
+
+```
+- "briefly summarise"       → "summarise"
+- "fundamentally new"       → "new"
+- "truly able to"           → "able to"
+- "extremely limited"       → "very small number" (restructure)
+- "gradually established"   → "established" (ok in context)
+```
+
+**Check**: Search for `\w+ly\b`. Evaluate each — most can be dropped.
+
+---
+
+### R8: Concrete over Abstract
+
+**Signal**: Abstract noun phrases that could be expressed more directly.
+
+**Fix**: Make the idea concrete. Use examples, metaphors, or simpler terms.
+
+```
+Abstract                          → Concrete:
+  "the mistaken identification   → "the mistaken belief in a fixed
+   and attachment to the self"        self and our clinging to it"
+  "corresponding mental functions" → "the mindset that aligns with them"
+  "discern the universal sequence  → "understand how the teachings
+   from shallow to deep"               progress from basic to advanced"
+  "mode of existence centered      → "a life centered on the Three Jewels"
+   on the Three Jewels"
+  "a field of specialisation"      → delete (unnecessary abstraction)
+  "ideological content"            → "ideas"
+```
+
+**Check**: If a noun phrase has 3+ words and feels like jargon, find a plainer way.
+
+---
+
+### R9: Terminology Alignment
+
+**Signal**: Terms that have established translations in the MPI terms database or
+prior publications (坐看云起, etc.).
+
+**Fix**: Use the established translation. Load `terms-search` skill and check:
+`python3 $MPI_PROJECT_ROOT/terms-search/search.py <term>`
+
+```
+Key distinctions from the 3 manuscripts:
+  人生佛教  → "Buddhism of Human Life" (NOT "Humanistic Buddhism")
+  人间佛教  → "Humanistic Buddhism"
+  禅宗      → "Chan" (not "Zen")
+  根机      → "faculties" (not "dispositions", not "root")
+  高僧大德  → pick one: "eminent monks" or "great masters" (not both)
+  假 (三性) → "false" (from emptiness perspective)
+  monks     → "monastics" (includes both monks and nuns — 含比丘比丘尼)
+  惑业苦    → "delusion, karma, and suffering" (logical order preserved)
+  出世乐    → keep consistent with "supreme bliss of Nirvana" used earlier
+  戒体      → don't use "precept essence" (hard to understand); expand to
+              "the mind of upholding the precepts"
+```
+
+**Check**: For any Buddhist technical term, verify against the terms DB before
+using a new translation. Consistency across manuscripts matters.
+
+---
+
+### R10: Missing Content Detection
+
+**Signal**: Chinese paragraph has multiple clauses/ideas, but English stops after
+1–2 sentences. Quoted speech, poems, rhetorical climaxes in CN are absent from EN.
+
+**Fix**: Flag as "Missing Content." Translate the missing portion.
+
+```
+Common patterns:
+  - 中文有4-5个短句，英文只有1-2句 → 漏翻了
+  - CN has a paragraph with quoted speech → EN paragraph ends before the quote
+  - 一些具有相当成就的前辈高僧... → entire passage skipped
+  - 内修与外弘也是同样... → entire paragraph missing
+  - 民众在接受教育期间，无法从教科书上对佛教获得正面了解 → line missing
+```
+
+**Check**: Compare CN and EN paragraph lengths. If CN is substantially longer but
+EN seems complete, re-read the CN carefully — something was likely dropped.
+
+---
+
+### R11: Source Faithfulness
+
+**Signal**: English adds concepts, metaphors, or explanations not present in the
+Chinese. Or English drops specific details that the Chinese includes.
+
+**Fix**: Remove additions. Translate dropped content. But restructure freely for
+natural English — don't mirror Chinese word order if it produces awkward results.
+
+```
+Additions to remove:
+  - "this addresses one of the most fundamental philosophical questions"
+    (not in CN → delete)
+  - "preserving the potential for future expression" (not in CN → delete)
+  - "making this school widely known in China" (not in CN → delete)
+
+Things to preserve:
+  - Quoted speech, idioms, and rhetorical questions — translate fully
+  - Logical connectors between sentences — don't skip them
+  - The speaker's distinctive voice and argument structure
+  - 讲法风格 — the master's teaching style should come through
+```
+
+**Check**: For each paragraph, ask: is there content in EN that has no basis in CN?
+Is there content in CN that has no corresponding EN? Fix both.
+
+---
+
+### R12: Sentence Structure Clarity
+
+**Signal**: English reads as "translationese" — word order follows Chinese,
+parallel structures are misaligned, logical flow is broken.
+
+**Fix**: Restructure for natural English. Reorder clauses. Align parallel items.
+
+```
+- "Despite different methods, your focus has always been Humanistic Buddhism"
+  → "Although the methods vary, they all center on Humanistic Buddhism"
+  (methods vs. focus — misaligned comparison)
+
+- "the root cannot be established"
+  → "we cannot establish the root" (add human subject)
+
+- Lists: keep verb forms parallel
+  "First, focus on building... Second, keep liberation at the center...
+   Third, highlight the unique spirit..."
+  (imperative verbs aligned)
+```
+
+**Check**: Read each sentence and ask: would a native English speaker structure it
+this way? If not, reorder.
+
+---
+
+### R13: Specific Word Fixes
+
+**Signal**: Certain English words have wrong connotations for the context.
+
+**Fix**: Use the recommended replacement.
+
+```
+"comeback"     → "return" (comeback = return to popularity, not return to roots)
+"evokes"       → "brings" / "gives rise to" (evokes is too formal)
+"entertain"    → "have" (entertain thoughts → have thoughts)
+"falls"        → "fades" (faith falls → faith fades)
+"reverse"      → "transform" (gentler)
+"escape"       → softer word in context
+"dismantle"    → "challenges" / "undoes" (dismantle is too aggressive)
+"head"         → "beginning" (head of the Eightfold Path → beginning)
+"none"         → "not many" (when the claim is "未提供多少" not "none at all")
+"function"     → "purpose" (in non-technical contexts)
+"object"       → "focus" (object of practice → focus of practice)
+"uncommon"     → "unique" / "distinctive" (不共 = not shared with other paths)
+"conduct and propagate" → "uphold and spread"
+"attainment of Buddhahood" → "enlightenment" (in some contexts, to avoid
+                            Buddha/Buddhahood repetition)
+"liberation"   → "liberation" is fine, but check if context means "解脱" or "出世"
+```
+
+---
+
+### R14: Positive Feedback — Praise the Translator (随喜)
+
+**Signal**: A passage reads well — accurate, natural, fluent. Or the translation
+as a whole shows consistent quality.
+
+**Action**: Praise the first-pass translator by name. The editor consistently opens
+or closes review sections with affirmations directed at the translator:
+
+```
+"随喜师兄整体翻译还是很好的，前后连贯，清晰"
+"随喜师兄翻译 准确流畅！"
+"随喜师兄上段和本段翻译 准确流畅"
+"随喜师兄查证出处"
+"整段翻译的很好"
+"整段翻译还是很棒的"
+"翻译一气呵成 很精彩"
+"很赞叹 简洁有力！"
+"这个功不唐捐翻译的真好"
+"随喜这个翻译！衔接的很好"
+"这个翻译很赞！"
+"这段翻译也很好"
+"整段翻译的还是很好的"
+"翻译的意思都表达出来了"
+"本段翻译的都很好，随喜赞叹！"
+```
+
+This matters for three reasons:
+1. It tells the translator what to preserve — don't accidentally "fix" what works
+2. It follows the deliberation protocol — rejoicing (随喜) comes first, before
+   any criticism. The translator should feel their effort is seen and valued
+3. It names the translator explicitly — "随喜师兄" — making the praise personal,
+   not generic. When reviewing, use the translator's name from the document title
+   (e.g. 妙蕊, 法轩, Fiona)
+
+## Workflow
+
+```
+1. Read source.dj + target.dj (full files)
+2. Apply R1–R13 in order, scanning the English line by line
+3. For each issue found, apply with patch or write to translation-findings.dj
+4. Note well-translated passages (R14)
+5. Final pass: read the full English aloud — does it flow?
+```
+
+## Pitfalls
+
+- Don't apply this skill before `translation-review` — terminology must be correct first.
+- Don't over-correct: some formal constructions are appropriate for certain passages.
+  Judge per context.
+- When converting nouns to verbs, keep the meaning intact — don't simplify away
+  doctrinal nuance.
+- The "we" subject is generally preferred but not absolute. If a passage describes
+  a general principle without a specific agent, passive/impersonal may be correct.
+- Positive feedback (R14) is not optional fluff — it guides what to preserve.
@@ -95,6 +95,7 @@ category of error. Don't try to catch everything in one scan.
 - Buddhist terminology against the MPI terms DB (see terms-db-alignment below)
 - Mistranslation of key terms, wrong proper names, garbled text
 - Mid-paragraph truncation: CN covers 3–5 clauses but EN stops after 1–2 sentences. Signal: CN has quoted speech, poems, or a rhetorical climax absent from EN. Flag as "Missing Content" not "Incomplete."
+- Use `references/common-issues-taxonomy.md` as a structured checklist for accuracy issues

 **Pass 2 — mechanical/formatting** (also mechanical, but easy to skip):
 - TOC format: AGENTS.md says TOC must be plain bullet list, no link targets. Strip `[I. Heading](#...)` markdown links if present.
@@ -218,12 +219,38 @@ Do not run extraction pipelines until scope is clear.
 - **Batch terminology lookups** — when checking many terms against the terms DB, run them in one `execute_code` script that loops over a query list and calls `search.py` via `subprocess.run`. One terminal call per term floods the context with repetitive output.
 - **Proofread ≠ translation review** — when the user says "校对" or "proofread" and the input is a DOCX manuscript with existing English, you are in proofread mode. Do NOT flag translation quality, terminology, or djot formatting. Do NOT apply patches to bilingual.dj unless asked. Write `edit-suggestions.dj` with manuscript-level issues only. If the user later asks for translation review of the same article, write findings to a separate `translation-findings.dj`.

+## Human Review Protocol (审议)
+
+When giving feedback to human translators — whether in a review team or as an AI
+assistant flagging issues — follow the Oriental Translation Workshop protocol.
+See `references/deliberation-protocol.md` for full guidance.
+
+Key points:
+- **Rejoice first** (随喜): affirm what works before flagging issues
+- **Three-tier issues**: Level 1 (spelling/grammar/format) — fix directly. Level 2
+  (omission/mistranslation/wordiness) — suggest or fix with tracked changes. Level 3
+  (citation versions / marginal wording) — discuss with translator
+- **Tone**: questions, not commands; collaborative inquiry, not correction
+- **Address translator as 菩萨** (Bodhisattva) — respectful peer
+
+## Common Issues Taxonomy
+
+Use `references/common-issues-taxonomy.md` as a structured checklist when reviewing.
+Categories:
+
+- **Accuracy**: omission, mistranslation (over-free, over-literal, misunderstanding,
+  wrong word choice), overtranslation, terminology errors
+- **Readability**: redundancy (long sentences, passive voice, nominalization),
+  poor structure (top-heavy sentences), wrong register, weak transitions
+
 ## References

 - `references/buddhist-terminology.md` — Chinese-English Buddhist term mappings and pitfalls
 - `references/terms-db-alignment.md` — Batch-aligning glossary terms against the MPI terms database
 - `references/translation-pitfalls.md` — Recurring CN→EN mistranslation patterns (关爱→compassion, 生生增上, etc.)
 - `references/proofreading-patterns.md` — DOCX/PDF extraction techniques, block-based pairing, common manuscript issues
+- `references/deliberation-protocol.md` — Oriental Translation Workshop review protocol: tiers, rejoicing, tone
+- `references/common-issues-taxonomy.md` — Structured taxonomy of accuracy and readability issues with examples

 ## Scripts

@@ -0,0 +1,174 @@
+# Common Translation Issues Taxonomy
+
+From 译文常见问题与案例示范 (Common Issues in Translation, 2026-03-30).
+Categorized by accuracy and readability.
+
+## Accuracy Issues
+
+Standard: convey meaning at the content level, not word-by-word correspondence.
+"Translation is not simply word conversion."
+"You must understand what thought it is actually trying to express."
+
+### 1. Omission (漏翻)
+
+Content present in source but absent from target.
+
+Example:
+> 随着黑白牌的运用，象征这部分已能为大家提供系统的学习和训练资料。
+>
+> With the help of the Black-and-White Cards, this approach now offers a structured
+> system of study.
+>
+> *Missing:* 学习和训练 (learning and training) — "study" only covers half.
+> Also: 象征这部分 (symbolizing this aspect) is dropped.
+
+### 2. Mistranslation (错翻)
+
+#### a. Over-free translation, weakening the original
+
+> "道德"一词，人们耳熟能详。即使在道德日渐边缘化的今天，人们依然会用"这人
+> 很有道德""这么做太缺德了"来评价周遭人事。
+>
+> "Morality" is a familiar term, and even in today's world, where it has become
+> increasingly marginalized, expressions like "immorality" are still commonly used
+> to describe certain behaviors and individuals.
+>
+> *Issue:* The source gives two concrete colloquial expressions ("这人很有道德" /
+> "这么做太缺德了") — the target collapses them into a single abstract "expressions
+> like 'immorality'." The vividness and specificity are lost.
+
+#### b. Over-literal translation, harming comprehension
+
+> 作为素菜馆，应该尽量提供绿色食品。
+>
+> A vegetarian restaurant should strive to offer green food.
+>
+> *Issue:* 绿色食品 = "safe and healthy food" (Chinese idiom), not
+> "green food" (color of food in English). → `safe and healthy options`
+
+#### c. Misunderstanding the source
+
+> 政府现在倡导文化自信，习主席提出的"讲仁爱，重民本，守诚信，崇正义，尚和合，求大同"。
+>
+> President Xi Jinping has called for a confident embrace of Chinese culture,
+> highlighting virtues such as...
+>
+> *Issue:* Two different subjects: the government advocates cultural confidence;
+> Xi proposed the six virtues. The target merges both into Xi alone.
+
+#### d. Wrong word choice causing misunderstanding
+
+> 提供一些通俗易懂的法宝
+>
+> with easy Buddhist materials
+>
+> *Issue:* 通俗易懂 means "accessible to a general audience," not "easy/simple."
+> The Dharma can be accessible but is never "simple." → `accessible`
+
+### 3. Overtranslation (多翻)
+
+Adding parentheticals or expansions not in the source.
+
+> 出家人不仅要对三宝、师长、道友建立没有染污的情感
+>
+> Monastics should cultivate pure and untainted emotions not only toward the Three
+> Jewels (the Buddha, the Dharma, the Sangha), their teachers (The Head Monk and
+> Abbot), and fellow practitioners...
+>
+> *Issue:* Parenthetical expansions like "(the Buddha, the Dharma, the Sangha)"
+> and "(The Head Monk and Abbot)" are not in the source and should be removed.
+
+### 4. Terminology Errors
+
+- 身心 → `body and heart mind` → should be `body and mind`
+- 甘露别院 → `Ganlu Bieyuan The Amrita Retreat Center` → official: `Amrita Retreat Center`
+- "六字" → `six characters` → should be `six words`
+
+### 5. Detail-Level Issues
+
+- Tone appropriateness
+- Citation source authority
+- CN→EN conversion rules: numerals, units, date formats
+- Proper noun handling: transliteration vs. translation
+
+## Readability Issues
+
+Standard: fluent sentences, graceful expression, matching target reader habits.
+"Conform to what foreign readers find readable."
+"Concise, clear, accurate, not draggy, meaning clear."
+
+### 1. Redundancy & Wordiness
+
+#### a. Long / nested sentences
+
+Sentences with too many clauses that can't be read in one breath. Split them.
+
+#### b. Passive voice overuse
+
+> 如果对肉食消费得少，乃至完全不消费，那么从业者自然随之减少，很多动物就可以摆脱被屠宰、割截的厄运。
+>
+> If meat consumption were reduced, or even eliminated entirely, then the number of
+> businesses involved would naturally be lessened. This way, many animals could be
+> spared from the adversity of being slaughtered and butchered.
+>
+> *Issue:* Three passives in two sentences. Active rewrite is more concise:
+> *If people consume less meat — or none at all — fewer will work in the industry,
+> and many animals will be spared the fate of slaughter and dismemberment.*
+
+#### c. Nominalization (动词名词化)
+
+> 我们前期倡导的正念禅修，比较重视培养觉知。
+>
+> In the early stages of mindfulness practice, we placed greater emphasis on
+> cultivating awareness.
+>
+> *Issue:* "placed greater emphasis on" is nominalized. → `we emphasized`
+
+### 2. Poor Structure (结构不当)
+
+Top-heavy sentences — the main clause arrives too late.
+
+> 没有如法的生活，不能严格要求自己，在今天这个红尘滚滚的时代，我们简直是没希望的。
+>
+> Weathering today's deluge of worldly temptation, without a Dharma-aligned lifestyle
+> and strict self-discipline, we have no hope.
+>
+> *Issue:* The condition clauses pile up before the main point. Restructure:
+> *Without a Dharma-aligned lifestyle and strict self-discipline, we have no hope
+> of weathering today's deluge of worldly temptations.*
+
+### 3. Wrong Word Choice (用词不当)
+
+> 当一个人开始关心生命的大问题时，对小问题自然云淡风轻。
+>
+> when we begin to contemplate the profound questions of existence, the banal
+> iterations of daily life lose their significance.
+>
+> *Issue:* "banal iterations" is obscure. Simplify.
+
+### 4. Weak Flow & Transitions (流畅性 & 连接词)
+
+> 修行的核心就是止恶行善。为什么某种行为能成为生命的主导？就是因为不断重复。
+>
+> The essence of cultivation lies in ceasing unwholesome actions and promoting
+> wholesome ones. But why do certain behaviors dominate our lives? Because of
+> constant repetition.
+>
+> *Issue:* Adding transition words improves flow. The "But" here creates a false
+> contrast — the second sentence is explanation, not counterpoint.
+
+## Detection Checklist
+
+When reviewing, run through:
+- [ ] Any missing content? (compare paragraph-by-paragraph)
+- [ ] Any added content? (parentheticals, expansions not in source)
+- [ ] Any over-literal renderings that don't work in English? (idioms, set phrases)
+- [ ] Any over-free renderings that lose specificity? (concrete examples → abstract)
+- [ ] Subject confusion? (two actors merged into one)
+- [ ] Buddhist terminology checked against terms DB?
+- [ ] Sentences too long to read in one breath? (split at natural breaks)
+- [ ] Passive voice clustering? (3+ in a paragraph)
+- [ ] Nominalized verbs? ("placed emphasis on" → "emphasized")
+- [ ] Top-heavy sentence structure? (main clause buried after long preamble)
+- [ ] Obscure word choices? (would a general reader understand?)
+- [ ] Missing or misleading transition words?
@@ -0,0 +1,90 @@
+# Deliberation Protocol (审议规程)
+
+From 东方译场审议手册 (Oriental Translation Review Manual, 2026-03-25).
+Guidance from Ven. Jiqun on translation review culture and process.
+
+## Core Standards
+
+1. **Accuracy (准确性)** — primary. Convey content-level meaning, not word-by-word
+   correspondence. Deepen accuracy iteratively; grasp the "inner spirit" rather than
+   fixating on literal vs free translation.
+
+2. **Readability (可读性)** — secondary. Fluent sentences, graceful expression. Do
+   not pursue endless revision; what is achievable now is the best for now.
+
+**Test**: invite 5–10 readers to read aloud and give feedback — is it clear or
+obscure? Is it concise? Is the meaning clear?
+
+## Decision-Making
+
+When opinions differ:
+- Compare which version is more accurate and more readable
+- Do NOT cling to your own view (不执着于己见)
+- If two people cannot decide, invite 5–10 to read and vote
+- Remember: the translation is for the READERS, not for yourself
+
+## Core Principle: Rejoice First (随喜)
+
+Before flagging issues, affirm what is good. Professional translation companies
+emphasize positive feedback to build translator confidence and good collaboration.
+Criticism alone — however precise — breeds resistance and harms the final result.
+
+In the Oriental Translation Workshop, rejoicing in others' merits cultivates
+sympathetic joy (随喜), compassion, selflessness, and boundless merit — while
+encouraging others' wholesome efforts.
+
+**Practice**: develop eyes that SEE the merits in a translation. Rejoice with
+genuine gladness. Examples:
+- "So many technical terms and complex logic here — you handled it beautifully!"
+- "This word choice is exactly right."
+- "The prose is so clean and fluid!"
+- "Excellent!" / "Good word choice!"
+
+## Three Principles for Giving Suggestions
+
+1. **Lower the self** — use compassionate, gentle, skillful language
+2. **Be diligent and attentive** — find the actual problems
+3. **Tier your suggestions** — make clear what MUST change, what COULD improve,
+   and what needs DISCUSSION
+
+## Three-Tier Issue System
+
+### Level 1: Spelling, Grammar, Format (拼写、语法、格式)
+
+**Action**: fix directly, keep tracked changes visible.
+
+May annotate for translator development:
+- "MPI format uses American English — `toward` not `towards`."
+- "Use `Chan` here, not `Zen`."
+- "MPI format does not use diacritics — `Yogacara` not `Yogācāra`."
+
+### Level 2: Omission, Mistranslation, Wordiness, Tone, Word Choice
+(漏翻、错翻、啰嗦、语气问题、用词问题)
+
+**Action**: preferably flag for translator to fix themselves; may also fix
+directly with tracked changes.
+
+Suggested language:
+- "Did we miss something here?"
+- "This sentence is quite long — could we split it into 2–3?"
+- "The translation here differs from the original. It reads as if the teacher
+  is saying X, but I think he means Y. What do you think?"
+- "This word feels a bit strong here — your thoughts?"
+- (After direct adjustment) "I tightened this sentence — does this work?"
+
+### Level 3: Citation Versions, Slightly Awkward Wording, Marginal Readability
+(引用版本不当、用词稍微不当、阅读体验略差)
+
+**Action**: flag and discuss with translator.
+
+Suggested language:
+- "I found another citation version that may be more concise — which do you prefer?"
+- "Could we use this word instead? Might fit better."
+- "Could you take another look at this passage? I feel readability could improve
+  but I'm not sure how — your thoughts?"
+
+## Tone Guide
+
+- Address the translator as 菩萨 (Bodhisattva) — respectful peer address
+- Use questions, not commands: "Could we...?" "What do you think?" "Would this work?"
+- Frame as collaborative inquiry, not correction
@@ -10,25 +10,22 @@ terms DB query, workflows, output format) are in AGENTS.md.

 ## Mindfulness Bell Corpus

-Register/style patterns in English Buddhist prose.
+English Buddhist prose — register/style reference for translation.

- Location: `/home/user/meta/www.files/public/The Mindfulness Bell/`
- 6 issues: MB92–MB97 (2023–2026), each ~84–116 pages
- Index: `index.yaml` (article titles, authors, pages)
- **Articles**: `~/documents/jingxin-lessons/Mindfulness Bell/articles/MB{92..97}/*.md` — 93 individual markdown files with YAML frontmatter. Read directly with `read_file`.
- Extraction script: `/tmp/extract_mb_articles.py` (re-run if PDFs change)
+- **PDFs + index**: `~/meta/www.files/public/The Mindfulness Bell/` — 6 issues (MB92–MB97, 2023–2026), `index.yaml` lists all articles by author/title/page
+- **Articles**: `~/documents/jingxin-lessons/Mindfulness Bell/MB{92..97}/*.md` — per-issue markdown files. Read with `read_file`.

-## Register Reference
-
-Four registers observed, useful as style targets:
+Four registers, useful as style targets:

 | Register | Example | Key features |
 |----------|---------|-------------|
-| Dharma talk | Thầy (MB94 "Roses and Garbage", MB97 "Go as a River") | Short sentences, concrete images, coined terms ("interbeing"), oral address ("It's clear?"), Sanskrit kept with narrative explanation |
-| Teaching lineage | Sister Đoan Nghiêm (MB93 "Our Patriarch Liễu Quán") | "We" voice, terms explained, cultural bridging ("like Jesus"), dates woven into narrative, still oral |
-| Personal narrative | Mick McEvoy (MB94 "Touching the True Nature") | First-person, confessional, borrowed Dharma vocabulary, emotional directness, vernacular |
+| Dharma talk | Thầy (MB94 "Roses and Garbage", MB97 "Go as a River") | Short sentences, concrete images, coined terms ("interbeing"), oral address, Sanskrit with narrative explanation |
+| Teaching lineage | Sister Đoan Nghiêm (MB93 "Our Patriarch Liễu Quán") | "We" voice, terms explained, cultural bridging ("like Jesus"), dates in narrative |
+| Personal narrative | Mick McEvoy (MB94 "Touching the True Nature") | First-person, confessional, borrowed Dharma vocabulary, vernacular |
 | Editorial | Brother Pháp Lưu (MB94 welcome letter) | Polished but warm, conceptual framing, "we" address |

+Quick-find in index: Thầy talks → `"Thích Nhất Hạnh"` + page ≤ 10; teachings → `"Sister"` or `"Brother"`; narratives → first-page articles by non-monastics; lineage → `"Patriarch"` or `"ancestor"`.
+
 ## Translation Principles

 1. **Terms**: Either keep Sanskrit w/ narrative explanation (bodhisattva, Māra) OR coin new English (interbeing, inter-are). Avoid clunky calques.
@@ -39,6 +36,16 @@ Four registers observed, useful as style targets:

 ## Pitfalls

+### Pre-flight accuracy check
+
+Before delivering a translation, run through the structured accuracy/readability
+taxonomy in `skills/translation-review/references/common-issues-taxonomy.md`.
+Catching these before review saves iteration cycles:
+- Omission, over-literal renderings, over-free renderings, subject confusion,
+  overtranslation, terminology errors
+- Long/nested sentences, passive voice clustering, nominalization, top-heavy
+  structure, obscure word choices, weak transitions
+
 ### 1:1 line mapping

 Each physical source line maps to exactly one physical target line. Never merge
@@ -79,13 +86,37 @@ opinion they haven't voiced yet. Once they pick, then apply consistently and
 annotate in the inline `{% %}` comment WHY this rendering was chosen so future
 editors know it was deliberate, not a slip.

-## Quick-Find in MB Corpus
+## Polishing (润色)

-Common article types to search for register examples:
- Thầy's Dharma talks: search index for "Thích Nhất Hạnh" + page ≤ 10
- Sister/brother teachings: search for "Sister" or "Brother" + "DHARMA TEACHING"
- Personal narratives: first-person voice, often pages 8–60
- Lineage/history: "Patriarch," "ancestor," dates in text
+After translating, do a deliberate readability pass before submitting for review.
+Read the English aloud — if a sentence can't be spoken in one breath, fix it.
+
+These are common patterns (not an exhaustive list). For the full taxonomy with
+more categories and examples, read
+`../translation-review/references/common-issues-taxonomy.md`.
+
+Examples of systematic adjustments:
+
+1. **Passive → active**. Passive clusters (3+ per paragraph) are the top
+   readability killer in CN→EN translation. `If meat consumption were reduced`
+   → `If people consume less meat`.
+2. **Nominalization → verb**. `placed emphasis on cultivating` → `emphasized
+   cultivating`; `the application of` → `applying`.
+3. **Sentence splitting**. If a sentence has 3+ clauses and runs past one breath,
+   split it. The source's period is not a contract — English readers need
+   shorter breath units than Chinese readers.
+4. **Academic → plain**. `constitute` → `make up`; `facilitate` → `help`;
+   `endeavor to` → `try to`; `in order to` → `to`. These texts are lectures
+   and conversations, not journal articles.
+5. **Register match**. Dharma talks and dialogues should sound spoken —
+   contractions, direct address, concrete images. If the English reads like a
+   paper abstract, warm it up. Check against the MB corpus registers for the
+   target genre.
+
+Do NOT apply these mechanically — each is a judgment call. A passive may be
+correct when the agent is unknown; a nominalization may be the right technical
+term. The goal is natural English that matches the source's register, not a
+formulaic rewrite.

 ## Meditation / Mindfulness Content

@@ -98,3 +129,4 @@ When translating guided meditation scripts, exercise guides, or posture instruct
 - `references/markdown-to-djot.md` — converting .docx.md to .dj for translation prep
 - `references/bilingual-format.md` — bilingual.dj layout: source/target adjacent, blank separator between pairs
 - `references/diacritics-convention.md` — diacritics rules
+- `../translation-review/references/common-issues-taxonomy.md` (cross-skill) — structured accuracy/readability checklist for pre-flight review
@@ -0,0 +1,107 @@
+# Review Comments for 佛法与企业管理
+# Translator: maple
+# Document: https://docs.google.com/document/d/1NmJKNavB4IBg56ZRBdS5ux9ObRVlHPnSxVmjjXCyITs/edit
+#
+# Google Drive API cannot create anchored comments on Google Docs.
+# The `anchor` field is silently ignored by Google Docs editor apps
+# (confirmed in official docs and by community since 2016).
+# These comments must be added manually by opening the document and
+# inserting each comment at the quoted text position.
+
+---
+
+## 1. Overall Praise (R14: 随喜)
+
+Quoted text: `佛法与企业管理`
+(anchored to the document title)
+
+随喜 maple 师兄翻译整体很好，准确流畅，尤其是把中文讲法风格自然地转成了英文对话语气。像 'Dao (the Way)' 这样的文化加注处理得很恰当。以下是一些优化建议，主要集中在语言简洁性和口语化方面。
+
+---
+
+## 2. Terminology: Chan (R9)
+
+Quoted text: `Create a Chan(Zen) Atmosphere`
+
+术语统一：禅→Chan（不用Zen），禅宗→Chan school。标题和正文的多处 'Chan(Zen)' 和 'Zen-like' 建议统一为 'Chan' 和 'Chan-like'。参考：坐看云起等已出版的书都统一用 Chan。
+
+Also applies to: `Zen-like atmosphere` (later in document)
+
+---
+
+## 3. Stray Digit
+
+Quoted text: `1This held back`
+
+有个小笔误：'1This held back' → 删去数字 '1'，改为 'This held back'。
+
+---
+
+## 4. Double Text Artifact
+
+Quoted text: `In Buddhism,  In Buddhism, the monastic community`
+
+有处文本重复：删去一个 'In Buddhism,'。
+
+---
+
+## 5. Typo: kingdom → kingdoms
+
+Quoted text: `kingdom may be won`
+
+笔误：'kingdom may be won' → 'kingdoms may be won' 或 'a kingdom may be won'。漏了复数或冠词。
+
+---
+
+## 6. Simplify Vocabulary (R3)
+
+Quoted text: `squandering`
+
+'squandering' 有些书面化，口语场景可用 'wasting' 或直接 'spending'。
+
+Also: 'insignificant' → 'tiny'/'small'; 'perpetuating' → 'creating more'。
+
+---
+
+## 7. Trim -ly Adverbs (R7)
+
+Quoted text: `completely new`
+
+英文现代风格可减少 -ly 副词。比如：
+- 'completely new' → 'fresh'
+- 'faithfully recorded' → 'recorded'
+- 'truly admirable' → 'admirable'
+能省则省。
+
+---
+
+## 8. Noun → Verb (R2)
+
+Quoted text: `the power of environment to attract, gain recognition, and create 'stickiness'`
+
+有几处名词偏多，可以试着转成动词。比如：
+'an environment that attracts, earns recognition, and keeps people coming back'
+
+---
+
+## 9. Split Long Sentences (R4)
+
+Quoted text: `How do we make the entrepreneur program better? How can we help everyone benefit from the teachings and bring Buddhist wisdom into their management? We've thought about these questions before, but not`
+
+有些句子比较长，可以考虑拆分为 2 句。TOC 后面的第一段 CN 含两个问句，EN 合并成一个句子偏长，读起来有点赶。
+
+---
+
+## 10. Conversational Tone (R6)
+
+Quoted text: `consequently`
+
+整体语气适合对话场景。个别词可以更口语化：'consequently' → 'so'；'therefore' → 'so'。这个讲座是对企业家班的开示，口语感越强越好。
+
+---
+
+## 11. Keep Active Voice (R1)
+
+Quoted text: `one's nature is hard to change`
+
+整体上已经大量用了 'we' 做主语，读者参与感很强。'one's nature' 在谚语语境下没问题。继续保持 'we' 为主就好。
				`@@ -0,0 +1 @@`
				`,user,17,20.06.2026 22:13,file:///home/user/.config/libreoffice/4;`
				`@@ -0,0 +1 @@`
				`,user,17,20.06.2026 22:14,file:///home/user/.config/libreoffice/4;`