Fix Japanese documentation errors in commands-legacy

[miyako]

Summary

Quality audit of i18n/ja/docusaurus-plugin-content-docs/*/commands-legacy/ revealed multiple categories of errors across the Japanese localization files. These include typos, duplicate particles, incorrect cross-references, missing links, broken katakana words from legacy HTML conversion artifacts, and inconsistent terminology.

Scope

Files inspected across 4 versions:

• current/commands-legacy/ (18 files)
• version-21/commands-legacy/ (1,212 files)
• version-21-R3/commands-legacy/ (18 files)
• version-21-R4/commands-legacy/ (18 files)

Issues Found

1. Typos and broken characters

File	Error	Correction
on-web-authentication-database-method.md	ダイアログオックス	ダイアログボックス
on-web-legacy-close-session-database-method.md	セッ ション (space in word)	セッション

2. Duplicate/extra particles (の, に, で)

File	Error	Correction
on-web-authentication-database-method.md	DIGESTモードのの例題	DIGESTモードの例題
on-web-authentication-database-method.md	にからメソッド	からメソッド
on-exit-database-method.md	の始めにで	の始めに
9 Blob files (version-21)	developer.4d.com でのの	developer.4d.com での
object-set-format.md (version-21)	変数ののピクチャ	変数のピクチャ
svg-set-attribute.md (version-21)	要素のの属性	要素の属性
graph.md (version-21)	データベースののResources	データベースのResources

3. Punctuation

File	Error	Correction
on-backup-startup-database-method.md	var $0 : Integer.	var $0 : Integer (trailing period in code)
on-server-shutdown-database-method.md	missing sentence-ending 。	add 。

4. Incorrect cross-references

File	Error	Should be
on-host-database-event-database-method.md L40	[Semaphore](semaphore)	[On Exitデータベースメソッド](on-exit-database-method)
on-host-database-event-database-method.md L41	method name missing + typo ホストデーターベース	[On Startupデータベースメソッド](on-startup-database-method) + ホストデータベース
on-host-database-event-database-method.md L42	3× [Semaphore](semaphore)	3× [On Exitデータベースメソッド](on-exit-database-method)
on-host-database-event-database-method.md L43	method name missing	[On Startupデータベースメソッド](on-startup-database-method)

Verified against English source at docs/commands-legacy/on-host-database-event-database-method.md and archived site at library.4d-japan.com.

5. Missing link

File	Issue
on-mobile-app-authentication-database-method.md L37	Missing [Go Mobile with 4D](https://developer.4d.com/go-mobile/) in See Also section

6. Inconsistent terminology (ブラウザ vs ブラウザー)

34 files used ブラウザ (without long vowel mark) while the standard Japanese loanword spelling is ブラウザー. Standardized across all versions.

7. Broken katakana from legacy HTML conversion (~63 files, version-21 only)

When the documentation was converted from the legacy HTML system (library.4d-japan.com), hard line wraps at ~80 columns introduced spurious spaces mid-word in katakana terms. Examples:

• メ ソッド → メソッド
• テーブ ル → テーブル
• データベー ス → データベース
• パラメー ター → パラメーター
• コ マンド → コマンド
• ネッ トワーク → ネットワーク
• ピ クチャ → ピクチャ
• ~30 more patterns

This affected ~63 files in version-21/commands-legacy/ only (not present in current, R3, or R4).

Root Causes

1. Legacy HTML conversion: The docs were migrated from an HTML-based system (archived at library.4d-japan.com) to Markdown/Docusaurus. Hard line wraps in the HTML source became literal spaces in the Markdown.
2. Template text: The でのの error in 9 Blob files comes from shared boilerplate text that was copied with the typo.
3. Translation error: The Semaphore cross-references in on-host-database-event-database-method.md appear to be a mistranslation — the translator may have confused the Semaphore command page with the On Exit/On Startup database method pages.
4. Incremental version workflow: Errors in current/ are replicated identically in version-21-R3/ and version-21-R4/ since these share the same 18-file subset.

Files Changed

112 files total across all 4 versions (187 lines changed).

[miyako]

Documentation Quality Audit Report

Directory: i18n/ja/docusaurus-plugin-content-docs

---

Summary

Metric	Value
Total files in scope	~8,750
Version directories	7 (current, version-18, 19, 20, 21, 21-R3, 21-R4)
Files sampled/searched	All .md files via grep patterns
Definite errors found	7
Strong editorial issues	8
Potential inconsistencies	3
Significant contradictions	1 (factual error)
Repeated/shared errors	Yes — most issues are duplicated across version directories

Overall quality assessment

The documentation is a partially-translated Japanese localisation of 4D platform docs (originally written in French, then English). English prose sections that remain untranslated show clear French influence (Gallicisms). The English that is present is mostly functional but contains a few definite errors, one factual mistake ("in seconds" for a count property), and several translated-from-French patterns that sound unnatural in English.

Most common error categories

1. Typos/missing spaces (repeated across versions)
2. Factual error (wrong unit label)
3. Gallicisms — French-influenced phrasing left over from the original translation
4. Untranslated English remnants in otherwise-Japanese content
5. Incorrect article before acronyms

---

1. Typos / Spelling

🔴 1.1 postion → position

current/WritePro/commands/4d-write-pro-attributes.md (lines 203, 517)

Context:

"Defines the vertical postion of an image or a text box expressed in a CSS dimension string"

Problem: Misspelling of "position"

Suggested correction: postion → position

Also affected:

• version-21-R3/WritePro/commands/4d-write-pro-attributes.md (lines 203, 517)
• version-21-R4/WritePro/commands/4d-write-pro-attributes.md (lines 203, 517)

---

🟡 1.2 reponse → response (needs verification)

current/Debugging/breakpoints.md (line 18)

Context:

`If (Value type(request.reponse.headers...`

Problem: reponse appears to be a misspelling of response. However, this is inside a code snippet — verify whether the actual 4D API property is literally reponse or if this is a doc typo.

Suggested correction: request.reponse.headers → request.response.headers (if not actual API name)

Also affected:

• version-21/Debugging/breakpoints.md (line 18)
• version-21-R3/Debugging/breakpoints.md (line 18)
• version-21-R4/Debugging/breakpoints.md (line 18)

---

2. Grammar

🔴 2.1 Subject-verb agreement: that need to → that needs to

current/API/QuotaManagerClass.md (line 119)

Context:

"a REST request that need to create an entity set will get a 429 HTTP status code"

Problem: Singular subject "a REST request" requires the verb form "needs"

Suggested correction:

"a REST request that needs to create an entity set will get a 429 HTTP status code"

Also affected:

• version-21-R4/API/QuotaManagerClass.md (line 119)

---

🟠 2.2 Incorrect article: a SDI → an SDI

current/language-legacy/Windows/open-form-window.md (line 138)

Context:

"this code creates a plain form window without menu bar in a SDI application on Windows"

Problem: "SDI" is pronounced "ess-dee-eye" (vowel sound), requiring "an"

Suggested correction: in a SDI application → in an SDI application

Also affected:

• version-21-R3/language-legacy/Windows/open-form-window.md (line 138)
• version-21-R4/language-legacy/Windows/open-form-window.md (line 138)

---

3. Punctuation / Spacing

🔴 3.1 Missing space: oran → or an

current/language-legacy/Windows/open-form-window.md (line 18)

Context:

"a POSIX path (string) to a .json file describing the form, oran object describing the form"

Problem: Missing space between "or" and "an"

Suggested correction: oran object → or an object

Also affected:

• version-21-R3/language-legacy/Windows/open-form-window.md (line 18)
• version-21-R4/language-legacy/Windows/open-form-window.md (line 18)

---

4. Duplicate Words

🔴 4.1 or or → or

current/WritePro/commands/4d-write-pro-attributes.md (line 160)

Context:

"Image attributes are used to handle pictures inserted or or added in the area."

Problem: Duplicated word "or"

Suggested correction:

"Image attributes are used to handle pictures inserted or added in the area."

Also affected:

• version-21-R3/WritePro/commands/4d-write-pro-attributes.md (line 160)
• version-21-R4/WritePro/commands/4d-write-pro-attributes.md (line 160)

---

5. Bad / Awkward Prose (Gallicisms and Translation Artifacts)

🟠 5.1 whatever the platform → regardless of the platform

current/WritePro/commands/4d-write-pro-attributes.md (line 127)

Context:

"Font(s) to be used by default as replacement if a font is not supported by the OS, whatever the platform"

Problem: "Whatever the X" is a direct calque from French ("quel que soit le X"). While borderline grammatical, it sounds unnatural in technical English.

Suggested correction: whatever the platform → regardless of the platform

All occurrences (11 total across all versions):

• current/Preferences/general.md (line 97): "whatever the 4D version"
• current/FormEditor/forms.md (line 234): "whatever the compatibility option"
• current/WritePro/commands/4d-write-pro-attributes.md (lines 100, 127)
• Same files in version-21-R3/ and version-21-R4/

---

🟠 5.2 the editors concerned → the relevant publishers/vendors

current/Desktop/drag-and-drop.md (line 226)

Context:

"UTI types are published in Apple documentations as well as by the editors concerned."

Problem: "The editors concerned" is a Gallicism (French: "les éditeurs concernés"). In English, "editors" in this context should be "developers" or "vendors", and "concerned" should be "relevant".

Suggested correction:

"UTI types are published in Apple's documentation as well as by the relevant vendors."

Also affected:

• version-21-R4/Desktop/drag-and-drop.md (line 226)

---

🟠 5.3 more particularly at → specifically at

current/Desktop/drag-and-drop.md (line 227)

Context:

"please refer to the Microsoft developer documentation (more particularly at http://msdn2.microsoft.com/...)"

Problem: "More particularly" is a French-influenced construction ("plus particulièrement"). In English, use "specifically" or "in particular".

Suggested correction:

"please refer to the Microsoft developer documentation (specifically http://msdn2.microsoft.com/...)"

Also affected:

• version-21-R4/Desktop/drag-and-drop.md (line 227)

---

🟠 5.4 which then attributes them a number → which then assigns them a number

current/Desktop/drag-and-drop.md (line 227)

Context:

"third-party editors can 'save' format names in the system, which then attributes them a number in return"

Problem: In French, "attribuer" means "to assign/allocate". In English, "attributes" is not used as a verb meaning "to assign". The correct verb is "assigns" or "allocates".

Suggested correction:

"...which then assigns them a number in return"

Also affected:

• version-21-R4/Desktop/drag-and-drop.md (line 227)

---

🟠 5.5 allows the setting of elements → allows you to set elements

current/Develop-legacy/xml.md (line 85)

Context:

"It allows the setting of elements directly within an XML structure via a 'pathname' type syntax, without necessarily having to indicate the complete pathname in order to reach it."

Problem: Heavy nominalization ("allows the setting of") is a French translation pattern. The phrase "without necessarily having to indicate the complete pathname in order to reach it" is also verbose.

Suggested correction:

"It allows you to target elements directly within an XML structure using a pathname-like syntax, without specifying the full path."

Also affected:

• version-21-R4/Develop-legacy/xml.md (line 85)

---

🟠 5.6 This formalization of the elements can be used to check

current/Develop-legacy/xml.md (line 56)

Context:

"This formalization of the elements can be used to check whether an XML document is in compliance"

Problem: Overly abstract nominalization from French. "In compliance" without specifying "in compliance with what" is also unclear (though the DTD is implied).

Suggested correction:

"These formal element definitions can be used to check whether an XML document is valid"

Also affected:

• version-21-R4/Develop-legacy/xml.md (line 56)

---

🟠 5.7 carried out at the level of form objects

current/Concepts/dt_string.md (line 39)

Context:

"This normalization is carried out at the level of form objects (variables or fields) hosting plain or multi-style text."

Problem: "At the level of" is a French calque ("au niveau de"). In English technical writing, use "in" or "within" or "for".

Suggested correction:

"This normalization is performed within form objects (variables or fields) hosting plain or multi-style text."

Also affected:

• version-21-R4/Concepts/dt_string.md (line 39)

---

🟠 5.8 is not considered as a document modification

current/WritePro/commands/4d-write-pro-attributes.md (line 100)

Context:

"A new value evaluated from a formula or a new image loaded from a URL is not considered as a document modification"

Problem: In English, the correct form is "considered (to be)" or simply "considered", not "considered as". "Considered as" is a French calque from "considéré comme".

Suggested correction:

"...is not considered a document modification"

Also affected:

• current/Concepts/dt_string.md (line 39): "are considered as a single \r"
• Same files in version-21-R3/ and version-21-R4/

---

6. Terminology / Consistency

🔴 6.1 Incorrect capitalization: macos → macOS

current/Desktop/drag-and-drop.md (line 226)

Context:

"(Uniform Type Identifier, macos only)"

Problem: Apple's official capitalisation is "macOS"

Suggested correction: macos only → macOS only

Also affected:

• version-21-R4/Desktop/drag-and-drop.md (line 226)

---

🔴 6.2 Uncountable noun: documentations → documentation

current/Desktop/drag-and-drop.md (line 226)

Context:

"UTI types are published in Apple documentations as well as by the editors concerned."

Problem: "Documentation" is uncountable in English. The plural form "documentations" is a French-influenced error.

Suggested correction: Apple documentations → Apple's documentation

Also affected:

• version-21-R4/Desktop/drag-and-drop.md (line 226)

---

7. Contradictions / Factual Errors

🔴 7.1 Wrong unit label: "(in seconds)" for a count property

current/API/QuotaManagerClass.md (line 115)

"The .nbEntitySets property contains the maximum number of REST entity sets allowed in memory for the current session (in seconds)"

Compare with lines 49 and 81 in the same file:

Line 49: "The .defaultEntitySetTimeout property contains the default inactivity timeout for REST entity sets stored in memory during the current session (in seconds)"

Line 81: "The .maxEntitySetTimeout property contains the maximum inactivity timeout value for REST entity sets stored in memory during the current session (in seconds)"

Issue: Lines 49 and 81 correctly describe timeout properties with "(in seconds)" — this is a duration. But line 115 describes nbEntitySets, which is a count (a maximum number), not a duration. The "(in seconds)" was clearly copy-pasted from the timeout properties.

Action: Remove "(in seconds)" from line 115 — it is definitively incorrect for a count property.

Also affected:

• version-21-R4/API/QuotaManagerClass.md (line 115)

---

8. Repeated / Shared Errors

8.1 Untranslated English in otherwise-Japanese content

current/WritePro/commands/4d-write-pro-attributes.md (line 100)

Context:

"...データベースから読み出された時点 )。 It is automatically set to true by 4D Write Pro as soon as a modification is done to the contents of the document, whatever the origin of the modification (user action or programming). Notes: ..."

Problem: Multiple English sentences remain untranslated within what should be a fully-Japanese paragraph. This affects the same entry across versions.

Also affected:

• version-21-R3/WritePro/commands/4d-write-pro-attributes.md (line 100)
• version-21-R4/WritePro/commands/4d-write-pro-attributes.md (line 100)

Action: Translate remaining English to Japanese, or clearly separate bilingual content.

---

8.2 Pattern: All "current" errors are duplicated in version directories

Every error found in current/ also exists in at least one of version-21-R3/ or version-21-R4/ (and often both). This is expected since version directories appear to be snapshots. However, it means:

• Fixing only current/ will leave the same errors in archived versions
• A global search-and-replace across the entire i18n/ja/docusaurus-plugin-content-docs/ tree is recommended for typos

---

Final Actionable Summary

🔴 Fix immediately — definite errors

#	Fix	Files
1	postion → position	*/WritePro/commands/4d-write-pro-attributes.md (×6 occurrences across 3 versions)
2	or or → or	*/WritePro/commands/4d-write-pro-attributes.md (×3)
3	oran → or an	*/language-legacy/Windows/open-form-window.md (×3)
4	Remove "(in seconds)" from nbEntitySets	current/API/QuotaManagerClass.md, version-21-R4/API/QuotaManagerClass.md
5	that need to → that needs to	current/API/QuotaManagerClass.md, version-21-R4/API/QuotaManagerClass.md
6	macos only → macOS only	current/Desktop/drag-and-drop.md, version-21-R4/Desktop/drag-and-drop.md
7	documentations → documentation	current/Desktop/drag-and-drop.md, version-21-R4/Desktop/drag-and-drop.md

🟠 Fix next — grammar and prose

#	Fix	Files
1	a SDI → an SDI	*/language-legacy/Windows/open-form-window.md (×3)
2	whatever the platform/version/option → regardless of the...	Multiple (11 occurrences)
3	the editors concerned → the relevant vendors	*/Desktop/drag-and-drop.md (×2)
4	which then attributes them → which then assigns them	*/Desktop/drag-and-drop.md (×2)
5	more particularly at → specifically at	*/Desktop/drag-and-drop.md, */Develop-legacy/xml.md (×4)
6	allows the setting of elements → allows you to target elements	*/Develop-legacy/xml.md (×2)
7	considered as a → considered (remove "as")	*/WritePro/commands/4d-write-pro-attributes.md, */Concepts/dt_string.md (×5)
8	carried out at the level of → performed within	*/Concepts/dt_string.md (×2)

🟡 Review — consistency / possible contradictions

#	Issue	Files
1	request.reponse.headers — is this actually the API property name, or a typo for response?	*/Debugging/breakpoints.md (×4)
2	Untranslated English sentences mixed into Japanese paragraphs	*/WritePro/commands/4d-write-pro-attributes.md (lines 100, 180, 278)
3	This formalization of the elements — acceptable or needs rewrite?	*/Develop-legacy/xml.md (×2)

🔧 Global fixes (safe search-and-replace)

These can be applied across the entire i18n/ja/docusaurus-plugin-content-docs/ tree:

Search: "postion"  →  Replace: "position"
Search: "or or added"  →  Replace: "or added"
Search: "form, oran object"  →  Replace: "form, or an object"
Search: "macos only"  →  Replace: "macOS only"
Search: "Apple documentations"  →  Replace: "Apple's documentation"
Search: "editors concerned"  →  Replace: "relevant vendors"
Search: "a SDI application"  →  Replace: "an SDI application"

Note: The "whatever the" → "regardless of the" replacement should be done manually per-context to ensure the surrounding sentence still reads naturally.

[miyako]

Instructions: Japanese Documentation Quality Audit & Fix

Context

This document captures the methodology, reasoning, and technical details for auditing and fixing the Japanese (i18n/ja) localization of the 4D platform documentation hosted at https://developer.4d.com/.

The documentation is built with Docusaurus from Markdown source files. The Japanese files were originally converted from a legacy HTML-based documentation system archived at https://library.4d-japan.com/.

---

Repository Structure

docs/                          # English source (current version)
versioned_docs/
  version-21/                  # English, frozen at v21
  version-21-R3/               # English, frozen at v21 R3
  version-21-R4/               # English, frozen at v21 R4
i18n/ja/docusaurus-plugin-content-docs/
  current/                     # Japanese, current version
  version-21/                  # Japanese, frozen at v21
  version-21-R3/               # Japanese, frozen at v21 R3
  version-21-R4/               # Japanese, frozen at v21 R4

Key principles of the versioning model:

1. docs/ is the English source of truth for the current version.
2. versioned_docs/version-X/ contains frozen English snapshots.
3. i18n/ja/.../current/ tracks docs/ — the Japanese translation of the current version.
4. Incremental versioning: Files unchanged between versions are omitted from newer version folders. Only modified files get a new copy.
5. current/, version-21-R3/, version-21-R4/ often share identical content (18 files in commands-legacy/), while version-21/ has the full legacy command set (1,212 files).

Implication for fixes:

• A fix to current/commands-legacy/foo.md likely needs to be applied to version-21-R3/ and version-21-R4/ as well (if the file exists there).
• version-21/ may have the same error OR different errors (it has many more files).
• Always check which versions contain a given file before fixing.

---

Reference Sources for Verification

1. English source files (primary)

Always compare the Japanese translation against the English source at:

• docs/commands-legacy/<filename>.md (current)
• versioned_docs/version-21/commands-legacy/<filename>.md (v21)

2. Archived legacy Japanese site (secondary)

The pre-Docusaurus Japanese documentation is archived at:

https://library.4d-japan.com/doc/4Dv20/index.ja.html

Individual command pages follow the pattern:

https://library.4d-japan.com/doc/4Dv20/4D/20.1/<Command-Name>.301-<id>.ja.html

This is useful for:

• Verifying whether an error existed in the original or was introduced during conversion
• Confirming correct Japanese text when the Markdown version is garbled
• Understanding what the original translator intended

3. Live documentation site

The built site is at https://developer.4d.com/. Use it to verify rendering behavior (e.g., whether HTML comments inside Markdown links are stripped correctly).

---

Common Error Categories in Japanese 4D Docs

Category 1: Broken Katakana from Hard Line Wraps

Root cause: The legacy HTML system used ~80-column hard wraps. When converted to Markdown, line breaks became spaces. In Japanese text, this inserts spaces mid-word in katakana terms.

Pattern: A space character between katakana characters that should form one word.

Detection:

grep -rn "[ァ-ヶー][ァ-ヶー] [ァ-ヶー]" version-21/commands-legacy/

Common broken patterns found:

Broken	Correct
メ ソッド	メソッド
テーブ ル	テーブル
データベー ス	データベース
パラメー ター	パラメーター
コ マンド	コマンド
ネッ トワーク	ネットワーク
セッ ション	セッション
ピ クチャ	ピクチャ
プ リエンプティブ	プリエンプティブ
ヘッ ダー	ヘッダー
フォ ルダ	フォルダー
ワー クソース	ワークソース

Fix approach: Use perl with explicit pattern list rather than a generic regex (which would cause false positives on legitimate word boundaries like モード デフォルト値):

perl -i -pe '
  s/メ ソッド/メソッド/g;
  s/テーブ ル/テーブル/g;
  s/データベー ス/データベース/g;
  # ... etc
' version-21/commands-legacy/*.md

False positive awareness: Some matches are legitimate:

• モード デフォルト値 — two separate words
• マイ ドキュメント — "My Documents" (Windows folder name)
• または 省略時 — normal Japanese syntax (particle + noun)

Scope note: This issue was found ONLY in version-21/ (which has 1,212 files from a more complete legacy conversion). The current/, R3/, and R4/ versions (18 files each) did not exhibit this problem.

---

Category 2: Duplicate Particles (のの, にから, にで)

Root cause: Translation/editing errors, likely from copy-paste or incomplete edits.

Detection:

grep -rn "のの" */commands-legacy/
grep -rn "にから" */commands-legacy/
grep -rn "にで" */commands-legacy/

Important: Not all のの are errors! In Japanese, のの can be legitimate (e.g., ものの meaning "although"). Always check context.

Template errors: The でのの pattern in 9 Blob-related files came from shared boilerplate text:

"developer.4d.com でのの Passing blobs... のページを参照して下さい。"

When you find the same error in multiple files with identical surrounding text, it's a template/boilerplate issue. Fix all instances and note this in the commit message.

---

Category 3: Incorrect Cross-References

Root cause: Translation error — the translator linked to the wrong command page.

Detection strategy:

1. Compare the [link text](url) in the Japanese file against the English source
2. Verify against the archived site if needed
3. Check if the reference makes semantic sense in context

Example found: In on-host-database-event-database-method.md, the table describing database events linked to [Semaphore](semaphore.md) where it should have linked to [On Exit database method] and [On Startup database method].

Verification method:

English source (docs/commands-legacy/on-host-database-event-database-method.md):
  Line 40: "The [On Exit database method](...) of the host database has just finished running"

Japanese (i18n/ja/.../on-host-database-event-database-method.md):
  Line 40: "ホストデータベースの [Semaphore](semaphore.md) データベースメソッドが実行を終了した"

Archived site (library.4d-japan.com):
  Confirms the English source is correct

Important distinction: Not all [Semaphore] references are wrong! In on-server-shutdown-database-method.md, the English source itself says "use the [Semaphore]" — this is the actual Semaphore command being recommended for client-side coordination. Always verify against the English source before "fixing."

---

Category 4: Terminology Inconsistency

Example: ブラウザ vs ブラウザー (browser)

Japanese loanword conventions (JIS Z 8301) recommend the long vowel mark (ー) for words ending in "-er", "-or", "-ar". Microsoft and most Japanese tech documentation now use ブラウザー.

Detection:

# Find instances without the long vowel mark, excluding already-correct ones
grep -rn "ブラウザ[^ー]" */commands-legacy/

Fix approach (negative lookahead to avoid doubling):

perl -i -pe 's/ブラウザ(?!ー)/ブラウザー/g' */commands-legacy/*.md

---

Category 5: Missing Content

Detection: Diff the structure of the Japanese file against the English source. Look for:

• Missing links in "See Also" sections
• Missing table rows
• Empty lines where content should be

Example: on-mobile-app-authentication-database-method.md had an empty line where [Go Mobile with 4D](https://developer.4d.com/go-mobile/) should have been.

---

Category 6: REF Comment System (NOT an error)

The 4D docs use a custom comment system:

<!--REF #_command_.Foo.Summary-->The Foo command does X.<!-- END REF-->

Sometimes <!-- END REF--> appears inside Markdown constructs like links:

[developer.<!-- END REF-->4d.com/go-mobile](https://developer.4d.com/go-mobile/...)

This looks broken but is intentional — HTML comments are stripped during rendering. The Summary REF block must end at a specific point in the text, and the docs build system handles this correctly. Do not "fix" these.

---

Workflow for Auditing

Phase 1: Discovery

# Count files
find i18n/ja/docusaurus-plugin-content-docs/*/commands-legacy/ -name "*.md" | wc -l

# Quick scan for common patterns
grep -rn "のの" */commands-legacy/ | grep -v "ものの"
grep -rn "[ァ-ヶー] [ァ-ヶー]" version-21/commands-legacy/ | wc -l
grep -rn "Semaphore" */commands-legacy/on-*-database-method.md

Phase 2: Verification

For each finding:

1. Check the English source at docs/commands-legacy/ or versioned_docs/
2. If unclear, check the archived site at library.4d-japan.com
3. Determine if it's a definite error, editorial issue, or false positive

Phase 3: Fix

Apply fixes in order of confidence:

1. Definite errors (typos, wrong cross-references) — fix immediately
2. Editorial issues (missing punctuation, inconsistent terminology) — fix next
3. Potential issues (needs verification) — flag for human review

Phase 4: Validate

# Verify no remaining instances of fixed patterns
grep -rn "ダイアログオックス" */commands-legacy/
grep -rn "Semaphore" */commands-legacy/on-host-database-event*

# Check for unintended damage
git diff --stat

---

Technical Notes on Safe Replacements

Perl negative lookahead (for terminology standardization)

When standardizing a term, use negative lookahead to avoid doubling:

# This avoids turning ブラウザー into ブラウザーー
perl -i -pe 's/ブラウザ(?!ー)/ブラウザー/g' file.md

Link format varies by version

• current/, version-21-R3/, version-21-R4/ use: [text](../commands/command-name)
• version-21/ uses: [text](command-name.md)

When fixing cross-references, use the correct link format for each version.

sed vs perl

• Use sed for simple substitutions
• Use perl when you need lookahead/lookbehind or complex regex
• On macOS, sed -i '' (empty string for backup extension); on Linux, sed -i

---

Commit Strategy

Group commits logically:

1. Definite errors — one commit covering all typos, duplicate particles, punctuation
2. Cross-reference fixes — separate commit (these are semantic changes, not typos)
3. Missing content — separate commit
4. Terminology standardization — separate commit (bulk change, easy to revert if needed)

Always mention:

• Which versions were affected
• The verification source (English file, archived site)
• Whether it's a repeated/template error

---

Pitfalls and Lessons Learned

1. Don't assume all instances of a pattern are errors. のの can be legitimate Japanese. [Semaphore] can be a correct reference. Always verify in context.

2. The English source can also have issues. The English docs have Gallicisms (French-influenced phrasing) because 4D is a French company. But for cross-reference verification, the English source is authoritative for link targets.

3. Version-21 is special. It has 1,212 files (the full legacy command set) while other versions have only 18 files. Most conversion artifacts are concentrated in version-21.

4. The <!-- END REF--> inside links is intentional. Don't fix it.

5. Check all versions before committing. A file that exists in current/ likely also exists identically in R3/ and R4/. Apply the fix to all copies.

6. Use the archived site for detective work. When the Markdown is garbled beyond recognition, the archived HTML version at library.4d-japan.com preserves the original text.

7. False positives in katakana regex. Legitimate word boundaries in Japanese (between compound nouns, before particles) will match [katakana] [katakana] patterns. Build a curated list of known broken patterns rather than doing blind regex replacement.

---

Summary of This Session's Output

Category	Files Fixed	Versions
Typos & broken characters	5	all 4
Duplicate particles	13	all 4 + v21-specific
Punctuation	2	all 4
Cross-references	4	all 4
Missing link	4	all 4
Terminology (ブラウザー)	34	all 4
Broken katakana (line wraps)	~63	version-21 only
Total	120 files

[miyako]

Here's the usage summary for "I18n ja docs quality audit":

---

Usage Summary

Metric	Value
Model	claude-opus-4.6 (exclusively)
User turns	12 (+ 1 PR creation)
API calls	152
Total input tokens	~13.65M
Total output tokens	~81K
Total tokens	~13.73M
Total duration	~25 min wall-clock API time
Total AIU	~1.32 AIU

Per-turn breakdown (top consumers)

Turn	Task	API calls	Input tokens	Output tokens
0	Initial audit of i18n/ja folder	47	2.5M	33K
4	Fix definite errors #1–4d#8	30	4.0M	12K
3	Expand audit to version-21/R3/R4	21	2.8M	12K
2	Focus on commands-legacy folder	20	2.1M	8K

---

Delegation Assessment

Verdict: Yes — highly delegable to a cheaper model (e.g. Claude Sonnet 5 or Haiku 4.5)

Why:

1. Task is read-heavy, not reasoning-heavy. 90%+ of tokens were input (reading markdown files). The actual reasoning was pattern-matching (find untranslated text, broken refs, formatting issues) — not novel problem-solving.
2. Mostly mechanical fixes. The edits were simple find-and-replace style corrections (wrong cross-references, raw English text in Japanese files, formatting errors).
3. Context window was the bottleneck, not intelligence. The high token count came from scanning many similar documentation files across version folders — a task Sonnet handles well.
4. No complex multi-step reasoning. Each fix was independent and self-contained.

Recommended setup for delegation:

• Model: claude-sonnet-5 (or even claude-haiku-4.5 for the mechanical fixes)
• Mode: autopilot for the fix phase; plan for the initial audit discovery
• Instructions template:

Audit the Japanese i18n documentation files in i18n/ja/docusaurus-plugin-content-docs/
for the following issues:
1. Untranslated English text that should be in Japanese
2. Broken cross-references (links to wrong pages)
3. Formatting errors from HTML→Markdown conversion
4. Inconsistent command naming

Focus on: commands-legacy/ folder across current, version-21, version-21-R3, version-21-R4.
For each issue found, fix it directly. Use the English source in docs/commands-legacy/ 
as reference for correct link targets.

This would cut costs by ~5–10× while producing equivalent results.