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

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 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 (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
• pages.es/common/tar.md
• pages.es/windows/tar.md (and others, with warning)
• pages/linux/tar.md (English/default)
• 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 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

# 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:

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.

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