@andreasnicolaou/rtl-detect

Modern, standards-based RTL (Right-to-Left) language detection for JavaScript/TypeScript. Detects if a locale is RTL, gets text direction, and lists all Unicode/ISO RTL languages.

Features

• Detect if a locale or language code is right-to-left (RTL)
• Script-aware: detects RTL by language or script subtag (e.g. az-Arab, pa-Arab)
• Get the text direction ('rtl' or 'ltr') for any locale
• List all supported RTL language codes (ISO 639) and script codes (ISO 15924)
• Fully immutable, type-safe, and fast
• Works in Node.js, browsers, and TypeScript projects

Installation & CDN Usage

Package Managers

# npm
npm install @andreasnicolaou/rtl-detect

# yarn
yarn add @andreasnicolaou/rtl-detect

# pnpm
pnpm add @andreasnicolaou/rtl-detect

CDN Usage

For direct browser usage without a build step:

<!-- unpkg CDN (latest version, unminified) -->
<script src="https://unpkg.com/@andreasnicolaou/rtl-detect/dist/index.umd.js"></script>

<!-- unpkg CDN (latest version, minified) -->
<script src="https://unpkg.com/@andreasnicolaou/rtl-detect/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (unminified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/rtl-detect/dist/index.umd.js"></script>

<!-- jsDelivr CDN (minified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/rtl-detect/dist/index.umd.min.js"></script>

Note: The library will be available as rtlLanguageDetector on the global scope when loaded via CDN in the browser.

Usage

ESM (ECMAScript Modules)

import {
  isRtlLanguage,
  getTextDirection,
  getRtlLanguageCodes,
  getRtlScriptCodes,
  parseLocale,
  RtlLanguageDetector,
} from '@andreasnicolaou/rtl-detect';

isRtlLanguage('ar'); // true
isRtlLanguage('az-Arab'); // true (RTL by script)
getTextDirection('fa-IR'); // 'rtl'
const rtlCodes = getRtlLanguageCodes();
const rtlScripts = getRtlScriptCodes();
const parsed = parseLocale('ar-EG');
RtlLanguageDetector.isRtlLanguage('he'); // true

CommonJS (Node.js require)

const {
  isRtlLanguage,
  getTextDirection,
  getRtlLanguageCodes,
  getRtlScriptCodes,
  parseLocale,
  RtlLanguageDetector,
} = require('@andreasnicolaou/rtl-detect');

isRtlLanguage('ar'); // true
isRtlLanguage('az-Arab'); // true (RTL by script)
getTextDirection('fa-IR'); // 'rtl'
const rtlCodes = getRtlLanguageCodes();
const rtlScripts = getRtlScriptCodes();
const parsed = parseLocale('ar-EG');
RtlLanguageDetector.isRtlLanguage('he'); // true

UMD (CDN/Browser)

<script src="https://unpkg.com/@andreasnicolaou/rtl-detect/dist/index.umd.min.js"></script>
<script>
  const { isRtlLanguage, getTextDirection, getRtlLanguageCodes, getRtlScriptCodes, parseLocale } = rtlLanguageDetector;
  isRtlLanguage('ar'); // true
  isRtlLanguage('az-Arab'); // true (RTL by script)
  getTextDirection('fa-IR'); // 'rtl'
  const rtlCodes = getRtlLanguageCodes();
  const rtlScripts = getRtlScriptCodes();
  const parsed = parseLocale('ar-EG');
  rtlLanguageDetector.isRtlLanguage('he'); // true
</script>

API

| Function/Export | Signature | Description | | ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | isRtlLanguage | (locale: string): boolean | Returns true if the locale is right-to-left — by base language or RTL script subtag (e.g. az-Arab). | | getTextDirection | (locale: string): 'rtl' \| 'ltr' | Returns the text direction for the given locale. | | getRtlLanguageCodes | (): readonly string[] | Returns a frozen array of all supported RTL language codes (ISO 639). | | getRtlScriptCodes | (): readonly string[] | Returns a frozen array of all supported RTL script codes (ISO 15924, e.g. Arab, Hebr). | | parseLocale | (locale: string): ParsedLocaleInfo \| undefined | Parses a locale into its language, script, and countryCode components. Strips encoding/variant suffixes (e.g., .UTF-8, @calendar=gregorian). | | RtlLanguageDetector | class | Static class with all the above as static methods. |

Types

| Type | Definition | Description | | ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------- | | TextDirection | 'rtl' \| 'ltr' | Text direction, either right-to-left or left-to-right | | ParsedLocaleInfo | { language: string; script?: string; countryCode?: string } | Parsed locale: language plus optional script and country code subtags |

How it works

This library parses a locale into its BCP 47 subtags (language, script, region) and checks them against immutable, ISO-compliant sets: RTL languages (ISO 639) and RTL scripts (ISO 15924). A locale is reported as RTL if its base language is RTL or it carries an RTL script subtag (e.g. az-Arab), so script-driven cases are handled even when the base language is otherwise LTR. It works in Node.js, browsers, and TypeScript projects, and is fully type-safe.

License

MIT

Contributing

Contributions are welcome! Please open issues or pull requests for improvements or new features.