# How the tldr Page Resolution Algorithm Works: Platform and Language Priority

> Understand the tldr page resolution algorithm. Discover how platform and language priority deterministically find command documentation for tldr clients.

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

---

**The tldr page resolution algorithm deterministically locates command documentation by normalizing the command name, constructing a platform priority list (host OS → common → other platforms), then performing a nested search across language preferences where platform priority always takes precedence over language fallback.**

The tldr-pages/tldr repository maintains the official [`CLIENT-SPECIFICATION.md`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) that governs how every compliant client must locate markdown documentation. Understanding the tldr page resolution algorithm ensures predictable behavior when commands exist across multiple platforms or language variants.

## Step 1: Command Name Normalization

Before searching the filesystem, the client transforms the requested command according to strict rules defined in [`CLIENT-SPECIFICATION.md`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) (lines 46-49). The client replaces all spaces with hyphens and converts the entire string to lowercase. This normalization ensures that `tldr "Git Checkout"`, `tldr git checkout`, and `tldr GIT-CHECKOUT` all resolve to the same canonical identifier.

## Step 2: Platform Priority Determination

The algorithm establishes a deterministic search order for platform directories. First, the client selects the **host platform** (e.g., `linux`, `windows`, `osx`) unless the user overrides this with the `--platform` (`-p`) flag (lines 51-57). The resulting platform priority list is:

1. The selected platform (host or user-specified)
2. The `common` platform directory
3. All remaining platform directories in any order

This hierarchy ensures that platform-specific optimizations take precedence over generic instructions when searching `pages/<platform>/<command>.md` (lines 84-90).

## Step 3: Language-Aware Page Search

After establishing the platform priority, the client determines the user's **language priority list** from the `LANG` and `LANGUAGE` environment variables (lines 89-105 and 119-132). Critically, the algorithm performs the platform search **inside each language tier** before falling back to the next language. This means the client checks `pages.<locale>/<platform>/<command>.md` for every platform in the priority list before moving to the next locale.

For example, on a Spanish Linux system requesting `tar`, the search order is:

- [`pages.es/linux/tar.md`](https://github.com/tldr-pages/tldr/blob/main/pages.es/linux/tar.md)
- [`pages.es/common/tar.md`](https://github.com/tldr-pages/tldr/blob/main/pages.es/common/tar.md)
- [`pages.es/windows/tar.md`](https://github.com/tldr-pages/tldr/blob/main/pages.es/windows/tar.md) (and others, with warning)
- [`pages/linux/tar.md`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/tar.md) (English/default)
- [`pages/common/tar.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tar.md) (English)
- Other English platforms

This structure ensures **platform priority wins over language**—the client prefers an English Linux-specific page over a Spanish `common` page.

## Step 4: Error Handling and Multiple Matches

If the client exhausts all platform and language combinations without finding a file, it displays an error message containing a pre-filled GitHub issue URL (`https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_name}`) and exits with a non-zero status code (lines 75-84).

When the client finds a page in a different platform than the host (e.g., falling back from `linux` to `windows`), it **may** emit a warning indicating the page originates from an alternate platform, though it must still display the first file found according to the priority order (lines 60-67 and 85-87).

## Directory Structure and Source Files

The resolution logic depends on a specific filesystem hierarchy enforced by the repository structure. The [`CLIENT-SPECIFICATION.md`](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md) file serves as the canonical algorithmic reference (lines 46-132), while the `pages/` directory contains English source files organized by platform (`common`, `linux`, `windows`, `osx`, etc.). Localized versions reside in `pages.<locale>/` directories (e.g., `pages.de/`, `pages.zh/`) mirroring the platform substructure. Maintainer utilities such as `scripts/set‑page‑title.py` and `scripts/set‑alias‑page.py` manage page metadata but do not influence runtime client resolution.

## Practical Client Usage Examples

```bash

# Default resolution uses host platform and detected language

tldr git

# Override platform to view macOS-specific instructions on Linux

tldr -p osx brew

# Force Italian language while maintaining platform priority

tldr -L it tar

```

When a page does not exist:

```bash
tldr nonexistent-command

# Output: No tldr page found for "nonexistent-command".

# Output: You can request a new page here: https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20nonexistent-command

# Exit code: 1

```

## Summary

- **Command normalization**: Spaces become hyphens, full string lowercased per lines 46-49
- **Platform priority**: Host/user-specified → common → other platforms (lines 51-67)
- **Language nesting**: Platform search executes completely within each language tier before language fallback (lines 89-132)
- **Error behavior**: GitHub issue link generation with non-zero exit code on total failure (lines 75-84)
- **Cross-platform warnings**: Clients may notify users when displaying pages from non-host platforms (lines 85-87)

## Frequently Asked Questions

### What happens if a page exists in `common` but not my specific platform?

The client displays the `common` page after failing to find the command in your host platform directory. According to the specification (lines 58-60), `common` serves as the second tier in the platform priority list, ensuring universal command documentation is available when platform-specific variants do not exist.

### How does the client prioritize language versus platform?

Platform priority always takes precedence over language preference. As implemented in lines 89-105 and 119-132, the client searches all platform directories (host, common, others) within your preferred language before falling back to English. This means a German Linux user will see the English Linux page before seeing a German `common` page.

### Can I request a page in a specific language regardless of my system locale?

Yes. While the algorithm defaults to parsing `LANG` and `LANGUAGE` environment variables, most clients provide a language flag (e.g., `-L it` for Italian) that overrides the automatic detection, inserting the specified locale at the top of the language priority list while maintaining the platform search order defined in the client specification.

### What exit code does the client return when no page is found?

The specification mandates a **non-zero exit code** when no file is found in any platform or language directory (lines 75-84). While the exact integer depends on the specific client implementation, all compliant clients must return a failure code and print the standardized error message including the GitHub issue creation URL.