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

> Discover the POSIX locale resolution algorithm tldr clients use for language detection. Learn how environment variables determine your preferred language or default to English.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: internals
- Published: 2026-03-05

---

**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`](https://github.com/tldr-pages/tldr/blob/main/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:

```python
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`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md)** – Contains the authoritative five-step algorithm definition (lines 191-201) and platform precedence rules (line 219).

- **[`scripts/build-index.js`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-more-info-link.py)** and **[`set-page-title.py`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) in the tldr-pages repository, specifically between lines 191 and 201, with platform precedence requirements at line 219.