The Algorithm Used for Language Detection by tldr Clients: POSIX Locale Resolution

tldr-pages clients use a deterministic five-step algorithm that reads the LANGUAGE and LANG environment variables to build a priority list of locales, selecting the first available language or defaulting to English if no match exists.

The tldr-pages repository maintains standardized multilingual command-line documentation across dozens of languages. To ensure consistent behavior across different client implementations, the project defines a strict algorithm used for language detection by tldr clients within its official client specification. This deterministic process resolves which localized page to serve based on standard POSIX locale settings while ignoring the special values C and POSIX.

How the Language Detection Algorithm Works

According to CLIENT-SPECIFICATION.md in the tldr-pages repository, the language resolution logic begins at line 191. The specification mandates that clients ignore the special locale values C and POSIX during resolution. The algorithm executes the following five steps defined at lines 195-201:

1. Read LANG – The client checks if the LANG environment variable is set. If unset, the client skips directly to step 5.

2. Parse LANGUAGE – If LANGUAGE is set, the client splits its colon-separated value into a priority list of locale identifiers (e.g., en:fr:de). If unset, the list begins empty.

3. Append LANG – The value of LANG (from step 1) is appended to the end of the priority list created in step 2.

4. Select the first available language – The client walks the priority list in order and selects the first language for which a corresponding tldr page exists on the system.

5. Fallback to English – If none of the languages in the priority list have a matching page, the client defaults to English (en).

Platform Precedence Requirements

The specification adds a critical precedence constraint at line 219. Clients must resolve platform before language for each candidate. This means for every language in the priority list, the client should first search for a page under the current platform directory (e.g., linux, osx, windows), then under common, before proceeding to the next language candidate.

Implementation Example

The following Python implementation demonstrates the algorithm exactly as specified in the client documentation:

import os

def detect_language():
    # 1. Read LANG

    lang = os.getenv('LANG')
    if not lang:
        return 'en'          # step 5 – fall back immediately

    # 2. Parse LANGUAGE into a list

    language_var = os.getenv('LANGUAGE', '')
    priority = [l for l in language_var.split(':') if l]   # ignore empty entries

    # 3. Append LANG

    priority.append(lang)

    # 4. Return first available language

    for loc in priority:
        if page_exists(loc):   # implementation-specific check

            return loc

    # 5. Fallback to English

    return 'en'

This logic mirrors the reference implementation and handles the environment variable parsing as required by the specification.

Key Files Defining Language Behavior

Several components in the tldr-pages repository govern how clients implement language detection:

• CLIENT-SPECIFICATION.md – Contains the authoritative five-step algorithm definition (lines 191-201) and platform precedence rules (line 219).

• scripts/build-index.js – Generates the page index including language metadata through the parseLanguage function, which clients rely on to validate available translations.

• scripts/set-more-info-link.py and set-page-title.py – Maintenance utilities that accept a -l/--language option, implementing the specification's language handling for automated repository management.

Summary

• The algorithm used for language detection by tldr clients follows a strict five-step process documented in CLIENT-SPECIFICATION.md lines 195-201.
• Resolution prioritizes the LANGUAGE variable as a colon-separated list, appends LANG as a final fallback, and ignores C and POSIX values.
• Clients must check platform-specific directories before common for each language candidate according to line 219.
• If no localized page matches, the algorithm defaults to English (en).
• The parseLanguage function in scripts/build-index.js provides the metadata infrastructure supporting this resolution.

Frequently Asked Questions

How does the tldr client prioritize the LANGUAGE variable over LANG?

The client splits LANGUAGE into an ordered list first, then appends LANG to the end of that list. This ensures that LANGUAGE acts as a priority queue while LANG serves as the final fallback, as defined in steps 2 and 3 of the specification.

What happens if both LANG and LANGUAGE are unset?

If LANG is unset, the client immediately proceeds to step 5 and defaults to English (en) without constructing a priority list, as specified at line 195 of CLIENT-SPECIFICATION.md.

Why does the algorithm check platform-specific pages before common pages?

As documented at line 219, the specification requires platform resolution before language resolution to ensure users receive documentation relevant to their operating system. For each language candidate, the client searches the current platform directory first, then common, before trying the next language.

Where is the official language detection algorithm documented?

The authoritative definition resides in CLIENT-SPECIFICATION.md in the tldr-pages repository, specifically between lines 191 and 201, with platform precedence requirements at line 219.

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