inline-word-links

name: inline-word-links description: Guidelines for adding inline cross-reference links to example sentences and notes. Includes common word reference table.

Inline Word Links

This skill covers how to add cross-reference links within example sentences and notes. These links allow users to click on any word in an example to navigate to its dictionary entry.

Coverage policy

Comprehensive polish (prompts/comprehensive_polish.md) requires full inline link coverage on every Japanese word in both example sentences AND the notes field, with noentry markers for words that lack entries. The rules below apply equally to Japanese text wherever it appears in an entry — there is no "examples only" carve-out anymore. The headword itself is not self-linked.

Link Format

The link format uses special Unicode delimiters:

⟦{surface|reading}→baseform：entry_id⟧

Components:

• ⟦ (U+27E6) - Opening bracket
• surface - The word as it appears in the sentence (may include furigana notation)
• → (U+2192) - Arrow separator
• baseform - The dictionary form of the word (for tooltip display)
• ： (U+FF1A) - Fullwidth colon separator
• entry_id - The dictionary entry ID (e.g., 00111_hon)
• ⟧ (U+27E7) - Closing bracket

CRITICAL: Semantic Verification

Links MUST be verified semantically, not programmatically.

Before adding any link, you MUST:

1. Understand the word's role in the sentence
2. Confirm the correct meaning - many words are homographs with different entries
3. Identify correct word boundaries - particles attach to words differently
4. Match to the correct entry - verify the gloss matches the intended meaning

Common Semantic Errors to Avoid

Verification Process

For each word you intend to link:

1. Read the full sentence to understand context
2. Identify the word's grammatical function
3. Look up the entry ID (use reference table below for common words)
4. Verify the entry's gloss matches the word's meaning in context
5. Only then add the link markup

Link Guidelines

DO Link (every Japanese word in examples and notes):

• Content words: nouns, verbs, adjectives, adverbs
• Particles that have entries (は, が, を, に, で, と, から, まで, の, へ, よ, ね, etc.)
• Demonstratives, pronouns, connectives
• Conjugated forms — link to the dictionary form
• Counter words attached to numerals
• Japanese phrases inside the notes field — collocations, related forms, fixed expressions, contrast pairs all get the same treatment as example sentences

DO NOT Link:

• The headword of the entry in its own examples or notes (no self-reference)
• Punctuation marks (。、？！「」『』…)
• Pattern placeholders (〜, …) — but the surrounding Japanese in a pattern like 〜に対して should be linked
• Names unless they have entries
• Arabic numerals (link the attached counter, not the digit)

For words that should be linked but lack an entry, use noentry (see below) and add the word to candidate_words.json with a note like "seen in entry XXXXX".

Using noentry

For words without dictionary entries:

⟦{矍鑠|かくしゃく}→矍鑠：noentry⟧

This preserves the markup for future linking but renders as plain text.

Always pair noentry with a candidate: when you mark a word noentry, also add it to candidate_words.json so the new-entry workflow can pick it up:

python3 build/manage_candidates.py add "矍鑠" "かくしゃく" "vigorous (despite age); seen in entry XXXXX"

This is what closes the dictionary in on itself: words that already appear get prioritized for entry creation.

Examples

Basic Example

Original:

"japanese": "{本|ほん}を{読|よ}む。"

With links:

"japanese": "⟦{本|ほん}→本：00111_hon⟧⟦を→を：00422_wo⟧⟦{読|よ}む→読む：00426_yomu⟧。"

Example with Particles

Original:

"japanese": "{私|わたし}は{日本語|にほんご}が{分|わ}かります。"

With links:

"japanese": "⟦{私|わたし}→私：02988_watashi⟧⟦は→は：00079_ha⟧⟦{日本語|にほんご}→日本語：00614_nihongo⟧⟦が→が：00051_ga⟧⟦{分|わ}かります→分かる：00463_wakaru⟧。"

Example with Conjugation

Original:

"japanese": "{彼|かれ}は{来|き}ませんでした。"

With links (note: conjugated forms link to dictionary form):

"japanese": "⟦{彼|かれ}→彼：01292_kare⟧⟦は→は：00079_ha⟧⟦{来|き}ませんでした→来る：00254_kuru⟧。"

Common Words Reference Table

Use this table for quick reference. For words not listed, search the dictionary.

Particles

Pronouns and Demonstratives

Common Verbs

Common Adjectives

Common Nouns

Common Adverbs

Additional Common Words

These are frequently encountered words not in the categories above:

Conjunctions

Word-ID Lookup Table

A pre-built lookup table is available at build/word_id_lookup.json for fast word→ID resolution. It is regenerated automatically by make index (via update_indexes.py).

The table has two indexes:

• by_reading — maps hiragana readings to entries (primary lookup method)
• by_headword — maps kanji/surface forms to entries

Each match includes id, headword/reading, gloss, and tier for disambiguation. For homophones (e.g., きく → 聞く/効く), check the gloss to select the correct entry.

# Example: look up a word by reading
python3 -c "
import json
with open('build/word_id_lookup.json') as f:
    data = json.load(f)
for e in data['by_reading'].get('きく', []):
    print(f\"{e['id']}: {e['headword']} - {e['gloss']}\")
"

Workflow for Adding Links

1. Read the sentence - Understand the full meaning
2. Identify each word - Note word boundaries carefully
3. Look up entry IDs - Use lookup table or reference table below
4. Verify semantically - Confirm each link matches intended meaning
5. Add markup - Apply the link format carefully
6. Validate immediately - Run validation to catch ID errors early:

   python3 build/validate.py 2>&1 | grep -A5 "Word link"
   

7. Review - Read through the linked sentence to verify

Tracking noentry Words

When you mark a word with noentry, consider tracking it for potential future entry creation. In your session log, include:

### Words marked noentry (candidates for future entries)
- ランナー (runner)
- セーフ (safe - sports)
- 丁目 (district number)

This helps identify gaps in the dictionary that may need filling.

Quality Checklist

Before finalizing links:

• Every link has been semantically verified
• No self-references (headword linking to itself)
• Punctuation is not linked
• Conjugated forms link to dictionary forms
• All entry IDs are valid
• Furigana is preserved correctly within links
• No spacing artifacts between links