@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)
• Get the text direction ('rtl' or 'ltr') for any locale
• List all supported RTL language codes (Unicode/ISO-compliant)
• 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,
  parseLocale,
  RtlLanguageDetector,
} from '@andreasnicolaou/rtl-detect';

isRtlLanguage('ar'); // true
getTextDirection('fa-IR'); // 'rtl'
const rtlCodes = getRtlLanguageCodes();
const parsed = parseLocale('ar-EG');
RtlLanguageDetector.isRtlLanguage('he'); // true

CommonJS (Node.js require)

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

isRtlLanguage('ar'); // true
getTextDirection('fa-IR'); // 'rtl'
const rtlCodes = getRtlLanguageCodes();
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, parseLocale } = rtlLanguageDetector;
  isRtlLanguage('ar'); // true
  getTextDirection('fa-IR'); // 'rtl'
  const rtlCodes = getRtlLanguageCodes();
  const parsed = parseLocale('ar-EG');
  rtlLanguageDetector.isRtlLanguage('he'); // true
</script>

API

| Function/Export | Signature | Description | | ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isRtlLanguage | (locale: string): boolean | Returns true if the locale or language code is right-to-left. | | 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. | | parseLocale | (locale: string): ParsedLocaleInfo \| undefined | Parses a locale string into its language and country code components. Automatically 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; countryCode?: string } | Parsed locale object with language and optional country code |

How it works

This library uses an immutable list of RTL language codes (Unicode/ISO-compliant) to determine text direction for any locale or language code. 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.