Difference Between pages and pages.locale Directories in tldr-pages

The pages/ directory stores the canonical English TLDR pages, while pages.<locale>/ directories contain translations of those pages into specific languages following the POSIX locale naming convention.

The tldr-pages repository organizes its command-line help documentation through a specific directory structure that separates the primary English source from multilingual translations. Understanding the difference between the pages/ and pages.<locale>/ directories is essential for contributors and client developers working with the tldr-pages project.

What Is the pages/ Directory?

The pages/ directory serves as the repository's source of truth, containing the canonical English versions of all TLDR pages. Located at the repository root, this directory houses platform-specific subdirectories that categorize commands by operating system or environment.

Inside pages/, you will find folders such as:

• common/ – Commands available across all platforms
• linux/ – Linux-specific commands
• windows/ – Windows-specific commands
• osx/ – macOS-specific commands
• android/ – Android-specific commands
• sunos/ – Solaris/Illumos-specific commands

Each subdirectory contains Markdown files named after the command they document (e.g., pages/common/pwd.md). These files follow the standard TLDR format with a command description and example usage. When users request help without specifying a language preference, tldr clients display these English pages by default.

What Are the pages.locale/ Directories?

The pages.<locale>/ directories are parallel structures that hold translations of the English pages into various languages. The <locale> component follows the POSIX locale naming convention (language[_COUNTRY]), allowing for both general language translations and region-specific variants.

Common examples include:

• pages.fr/ – French translations
• pages.es/ – Spanish translations
• pages.de/ – German translations
• pages.zh/ – Simplified Chinese translations
• pages.zh_TW/ – Traditional Chinese (Taiwan) translations
• pages.pt_BR/ – Brazilian Portuguese translations

Each localized directory mirrors the platform layout of the main pages/ directory, containing the same subdirectories (common/, linux/, windows/, etc.). The Markdown files within share identical filenames with their English counterparts but contain translated descriptions and examples while preserving the TLDR placeholder syntax (e.g., {{path/to/file}}).

According to the repository's CONTRIBUTING.md, language-specific directories must follow the pattern pages.<locale> to ensure clients can locate translations correctly.

Key Differences Between pages and pages.locale

Understanding the distinction between these directory types helps clarify the repository architecture:

Content Authority

• pages/ contains the primary English source files that serve as the reference for all translations
• pages.<locale>/ contains derivative translations that must stay synchronized with the English originals

Naming Convention

• The English directory uses the simple name pages
• Translation directories append the locale code with a dot separator (e.g., pages.fr, pages.pt_BR)

Fallback Behavior

• If a translation is missing for a specific command, clients automatically fall back to the English version in pages/
• This ensures users always receive help documentation even when translations are incomplete

Maintenance Workflow

• Updates to command functionality should first modify files in pages/
• Translators then propagate these changes to the appropriate pages.<locale>/ directories

How Clients Use These Directories

The tldr client specification defines how applications should locate and display pages from these directories. When a user requests documentation for a command, the client follows a specific resolution order based on environment variables and directory structure.

Environment Variable Configuration

Clients typically check the LANG or TLDR_LANGUAGE environment variables to determine which locale to prioritize:

# Display French translation if available

LANG=fr_FR tldr ls

# Or set for the entire session

export LANG=fr_FR
tldr tar

Resolution Algorithm

According to CLIENT-SPECIFICATION.md, clients implement the following logic:

1. Check for the command in pages.<locale>/ matching the requested language
2. If not found, check for the command in pages/ (English)
3. If still not found, return an error indicating the page doesn't exist

This fallback mechanism ensures that users with incomplete translations still receive functional documentation from the canonical English source.

Practical Examples

Viewing Directory Structure

To explore the relationship between English and localized pages:

# Navigate to repository root

cd $(git rev-parse --show-toplevel)

# View English pages structure

ls pages/

# Output: android  common  linux  osx  sunos  windows

# View French translation structure (mirrors English)

ls pages.fr/

# Output: common  linux  windows

Comparing Content

To see how a specific command differs between English and a translation:

# View English version of pwd

cat pages/common/pwd.md

# View Japanese translation (if exists)

cat pages.ja/common/pwd.md

Checking Translation Coverage

To verify whether a specific translation exists before attempting to use it:

# Check if Spanish translation exists for tar

if [ -f "pages.es/common/tar.md" ]; then
    echo "Spanish translation available"
else
    echo "Falling back to English"
fi

Summary

• The pages/ directory contains the canonical English TLDR pages organized by platform subdirectories (common/, linux/, windows/, etc.)
• The pages.<locale>/ directories contain translations following the POSIX locale naming convention (e.g., pages.fr/, pages.zh_TW/), mirroring the structure of pages/
• Clients prioritize localized pages when the LANG environment variable matches, automatically falling back to English if a translation is missing
• Contributors should modify pages/ first when updating command documentation, then propagate changes to relevant pages.<locale>/ directories

Frequently Asked Questions

What happens if a translation is missing for a specific command?

If a client requests a page in a specific locale (e.g., pages.de/) and the file does not exist, the client automatically falls back to the English version in pages/. This ensures users always receive documentation even when translations are incomplete, maintaining functionality across all supported languages.

How do I add a new language translation to the repository?

To add a new language, create a directory named pages.<locale>/ where <locale> follows the POSIX standard (e.g., pages.pt_BR/ for Brazilian Portuguese). Copy the platform subdirectory structure from pages/ (common/, linux/, etc.) and translate the Markdown content while preserving the TLDR placeholder syntax. Submit these files through a pull request following the contribution guidelines in CONTRIBUTING.md.

Why does the English directory use pages/ instead of pages.en/?

The repository uses pages/ as the canonical source to maintain backward compatibility and simplify the client specification. When the project started, it only supported English, so pages/ became the default. As translations were added, the pages.<locale>/ pattern was established for non-English content, with clients treating pages/ as the fallback when no specific locale matches or when the requested language is English.

Can I override the language setting temporarily without changing system locale?

Yes, most tldr clients respect the LANG environment variable for temporary overrides. You can prefix your command with the desired locale:

LANG=es_ES tldr tar

Alternatively, some clients support a --language flag or TLDR_LANGUAGE environment variable. Check your specific client implementation in CLIENT-SPECIFICATION.md for exact syntax, as behavior may vary between the official Python, Node.js, and C clients.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}