Inline Word Links

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:

• Content words (nouns, verbs, adjectives, adverbs)
• Particles when they have dedicated entries
• Words that appear in the dictionary

DO NOT Link:

• The headword of the entry in its own examples (no self-reference)
• Punctuation marks (。、？！「」)
• Words not in the dictionary - use noentry instead
• Names unless they have entries

Using noentry

For words without dictionary entries:

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

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

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