@timkit/url-lang

URL replacement utilities for adding language codes to URLs. Supports both path-based and subdomain-based internationalization strategies.

Installation

npm install @timkit/url-lang

Features

• ✅ Path-based language codes (example.com → example.com/fr)
• ✅ Subdomain-based language codes (example.com → fr.example.com)
• ✅ Wildcard exclusion patterns (/api/*, *.pdf)
• ✅ Prevents duplicate language codes
• ✅ TypeScript support
• ✅ Zero dependencies
• ✅ Fully tested with Vitest

Usage

Basic Example

import { replaceUrl } from '@timkit/url-lang';

const result = replaceUrl({
  url: 'https://example.com/about',
  langCodeToAdd: 'fr',
  currentLangCodes: ['en', 'fr', 'es', 'de'],
  mainDomain: 'example.com',
  excludedLinkPatterns: [],
  subdomainReplacement: false
});

console.log(result); // 'https://example.com/fr/about'

Path-Based Translation

replaceUrl({
  url: '/about',
  langCodeToAdd: 'fr',
  currentLangCodes: ['en', 'fr', 'es'],
  mainDomain: 'example.com',
  excludedLinkPatterns: [],
  subdomainReplacement: false
});
// Returns: '/fr/about'

Subdomain-Based Translation

replaceUrl({
  url: 'https://example.com/about',
  langCodeToAdd: 'fr',
  currentLangCodes: ['en', 'fr', 'es'],
  mainDomain: 'example.com',
  excludedLinkPatterns: [],
  subdomainReplacement: true
});
// Returns: 'https://fr.example.com/about'

Exclusion Patterns

Exclude specific URLs from language code insertion using wildcard patterns:

replaceUrl({
  url: '/api/users',
  langCodeToAdd: 'fr',
  currentLangCodes: ['en', 'fr'],
  mainDomain: 'example.com',
  excludedLinkPatterns: ['/api/*', '/wp-admin/*', '*.pdf'],
  subdomainReplacement: false
});
// Returns: '/api/users' (unchanged)

Supported Pattern Syntax

• /api/* - Matches any URL starting with /api/ (including /api/ itself)
• *.pdf - Matches any URL ending with .pdf
• /uploads/*.jpg - Matches /uploads/ + anything + .jpg
• # - Matches any URL containing # (anchor links)
• /wp-admin/ - Matches any URL containing /wp-admin/

The wildcard * matches zero or more characters.

Pattern Matching Helper

You can also use the pattern matching function independently:

import { matchesExclusionPattern } from '@timkit/url-lang';

matchesExclusionPattern('/api/users', '/api/*'); // true
matchesExclusionPattern('/api/', '/api/*'); // true
matchesExclusionPattern('document.pdf', '*.pdf'); // true
matchesExclusionPattern('#section', '#'); // true

API

replaceUrl(options: UrlReplacerOptions): string

Replaces or adds a language code to a URL based on the specified strategy.

Options

• url (string): The URL to process (absolute or relative)
• langCodeToAdd (string): Language code to add (e.g., 'fr', 'es', 'de')
• currentLangCodes (string[]): Array of all known language codes for detection
• mainDomain (string): Main domain name without www (e.g., 'example.com')
• excludedLinkPatterns (string[]): Array of URL patterns to exclude
• subdomainReplacement (boolean): Use subdomain (true) or path (false) strategy

Returns

The URL with the language code added, or the original URL if excluded or invalid.

matchesExclusionPattern(url: string, pattern: string): boolean

Checks if a URL matches an exclusion pattern.

Parameters

• url (string): The URL to test
• pattern (string): The pattern to match against

Returns

true if the URL matches the pattern, false otherwise.

Real-World Examples

WordPress Site

const options = {
  langCodeToAdd: 'es',
  currentLangCodes: ['en', 'es', 'fr'],
  mainDomain: 'myblog.com',
  excludedLinkPatterns: [
    '/wp-admin/*',
    '/wp-content/*',
    '/wp-includes/*',
    '/feed/*'
  ],
  subdomainReplacement: false
};

replaceUrl({ ...options, url: 'https://myblog.com/about' });
// 'https://myblog.com/es/about'

replaceUrl({ ...options, url: '/wp-admin/post.php' });
// '/wp-admin/post.php' (excluded)

replaceUrl({ ...options, url: '/wp-content/uploads/image.jpg' });
// '/wp-content/uploads/image.jpg' (excluded)

SaaS Platform

const options = {
  langCodeToAdd: 'de',
  currentLangCodes: ['en', 'de', 'fr', 'es'],
  mainDomain: 'myapp.io',
  excludedLinkPatterns: ['/api/*', '/auth/*', '*.json'],
  subdomainReplacement: true
};

replaceUrl({ ...options, url: 'https://myapp.io/dashboard' });
// 'https://de.myapp.io/dashboard'

replaceUrl({ ...options, url: 'https://myapp.io/api/users' });
// 'https://myapp.io/api/users' (excluded)

TypeScript

Full TypeScript support with exported types:

import type { UrlReplacerOptions } from '@timkit/url-lang';

const options: UrlReplacerOptions = {
  url: '/about',
  langCodeToAdd: 'fr',
  currentLangCodes: ['en', 'fr'],
  mainDomain: 'example.com',
  excludedLinkPatterns: [],
  subdomainReplacement: false
};

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Build the package
npm run build

# Development mode (watch for changes)
npm run dev

License

MIT