# Difference Between pages and pages.locale Directories in tldr-pages > Understand the tldr-pages difference between pages/ and pages./ directories. Discover how canonical English pages and translated locale pages are organized for clarity. - Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr) - Tags: internals - Published: 2026-03-05 --- **The `pages/` directory stores the canonical English TLDR pages, while `pages./` 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./` 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`](https://github.com/tldr-pages/tldr/blob/main/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./`** directories are parallel structures that hold translations of the English pages into various languages. The `` 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`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md), language-specific directories must follow the pattern `pages.` 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./` 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./` 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: ```bash # 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`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md), clients implement the following logic: 1. Check for the command in `pages./` 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: ```bash # 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: ```bash # 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: ```bash # 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./`** 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./` 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./` where `` 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`](https://github.com/tldr-pages/tldr/blob/main/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./` 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: ```bash 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`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) for exact syntax, as behavior may vary between the official Python, Node.js, and C clients.