Overview

Relevant source files

• doc/help.jax
• doc/intro.jax
• doc/spell.jax
• doc/tags-ja
• doc/terminal.jax

Purpose and Scope

The vimdoc-ja project provides comprehensive Japanese-language translations of Vim's documentation system. It maintains translated versions of all core Vim help files, a Japanese tag index for help navigation, and integration mechanisms that allow Japanese-speaking users to access Vim's full documentation in their native language.

This page covers the overall architecture and organization of the translation project. For details on specific subsystems:

• Documentation navigation and help system: see Documentation System and Help
• Tag indexing mechanics: see Tag Index and Symbol Reference
• Terminal documentation specifics: see Terminal Integration and Display

Project Structure

The vimdoc-ja project consists of two primary components:

1. Tag Index (doc/tags-ja): A comprehensive mapping of help tags to their locations in Japanese documentation files
2. Translated Documentation Files (.jax files): Japanese versions of Vim's help files, maintaining the same structure as English .txt files

Documentation File Format

Japanese documentation files use the .jax extension (instead of .txt for English files). Each .jax file corresponds to a specific English help file:

English File	Japanese File	Purpose
help.txt	help.jax	Main help entry point
terminal.txt	terminal.jax	Terminal window documentation
spell.txt	spell.jax	Spell checking system
options.txt	options.jax	All Vim options
eval.txt	eval.jax	Expression evaluation

Tag Index System Architecture

Sources: doc/tags-ja1-100

The tags-ja file follows Vim's standard tag file format with UTF-8 encoding:

• Line 1: File encoding declaration !_TAG_FILE_ENCODING utf-8 //
• Subsequent lines: Tab-separated entries in format: {tag}\t{file}\t{pattern}

Tag Entry Examples from tags-ja

!	change.jax	/*!* !!	change.jax	/*!!* 'spell'	spell.jax	/*'spell'* :terminal	terminal.jax	/*:terminal* term_start()	terminal.jax	/*term_start()* 

Sources: doc/tags-ja1-10

Documentation Coverage by Category

Sources: doc/help.jax44-250

Tag Index Structure and Scale

The tags-ja file contains comprehensive mappings for all Vim documentation features:

Sources: doc/tags-ja1-1000

Tag Categories and Patterns

The tag index organizes entries by type using consistent naming patterns:

Tag Pattern	Description	Example	Target File
'option'	Vim option names	'spell'	spell.jax
:command	Ex commands	:terminal	terminal.jax
func()	Functions	term_start()	terminal.jax
*marker*	Help markers	*spell*	spell.jax
CTRL-key	Control key combinations	CTRL-W	various
$VAR	Environment variables	$VIMRUNTIME	starting.jax

Sources: doc/tags-ja1-100

Documentation File Internal Structure

Each .jax file maintains the same internal structure as its English counterpart, with Japanese translations:

Sources: doc/terminal.jax1-50

Integration with Vim's Help System

The vimdoc-ja project integrates seamlessly with Vim's native help system:

Sources: doc/help.jax1-50

Help Command Flow

When a user executes :help {subject}:

1. Vim reads the 'helplang' option (e.g., "ja,en")
2. Searches for tags-ja in documentation directories
3. Looks up {subject} in the tag index
4. Opens the corresponding .jax file at the specified pattern
5. Falls back to English tags and .txt files if not found

File Organization in Repository

vimdoc-ja/ ├── doc/ │ ├── tags-ja # Main tag index (636.21 importance) │ ├── help.jax # Main help file (40.86 importance) │ ├── terminal.jax # Terminal docs (80.08 importance) │ ├── spell.jax # Spell checking (66.51 importance) │ ├── options.jax # Options reference │ ├── eval.jax # Expression evaluation │ ├── cmdline.jax # Command-line interface │ ├── pattern.jax # Pattern matching │ └── [other .jax files] # Additional documentation 

Sources: doc/tags-ja1-10 doc/help.jax1-10 doc/terminal.jax1-10 doc/spell.jax1-10

Documentation Statistics

The vimdoc-ja project provides extensive coverage:

• Tag Index Entries: 40,000+ tags in tags-ja
• Documentation Files: 100+ .jax files covering all Vim features
• Content Categories:
  • Basic editing (help, intro, editing, motion, change)
  • Advanced features (eval, channel, terminal, spell)
  • Configuration (options, starting, autocmd)
  • Programming support (syntax, indent, quickfix)
  • Language support (mbyte, mlang, arabic, etc.)

Sources: doc/tags-ja1-100 doc/help.jax44-250

Key Documentation Entry Points

Sources: doc/help.jax1-250

Translation Maintenance

The project maintains synchronization with upstream Vim documentation through:

1. Version Tracking: Each .jax file header indicates the Vim version and last change date
   • Example: *terminal.txt* For Vim バージョン 9.1. Last change: 2025 Nov 28
2. Tag Consistency: tags-ja entries match the exact tag patterns in .jax files
3. Structure Preservation: Japanese files maintain the same section numbering and tag anchors as English originals

Sources: doc/terminal.jax1-5 doc/spell.jax1-5 doc/help.jax1-5