{"id":22430099,"url":"https://github.com/2wce/speaking-url-ts","last_synced_at":"2025-08-01T11:32:14.609Z","repository":{"id":253268884,"uuid":"842975675","full_name":"2wce/speaking-url-ts","owner":"2wce","description":"Generate a slug – transliteration with a lot of options","archived":false,"fork":false,"pushed_at":"2024-12-02T18:05:09.000Z","size":1189,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-02T19:22:48.382Z","etag":null,"topics":["speakingurl","transliteration","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/2wce.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["2wce"]}},"created_at":"2024-08-15T14:09:24.000Z","updated_at":"2024-12-02T18:05:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"d44bff73-0279-497a-bc9e-8e32ef16e127","html_url":"https://github.com/2wce/speaking-url-ts","commit_stats":null,"previous_names":["2wce/speaking-url-ts"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2wce%2Fspeaking-url-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2wce%2Fspeaking-url-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2wce%2Fspeaking-url-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2wce%2Fspeaking-url-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/2wce","download_url":"https://codeload.github.com/2wce/speaking-url-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228371014,"owners_count":17909389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["speakingurl","transliteration","typescript"],"created_at":"2024-12-05T21:07:20.080Z","updated_at":"2024-12-05T21:07:20.589Z","avatar_url":"https://github.com/2wce.png","language":"TypeScript","funding_links":["https://github.com/sponsors/2wce"],"categories":[],"sub_categories":[],"readme":"# **speaking-url-ts**\n\n[![Version](https://img.shields.io/npm/v/speaking-url-ts.svg)](https://www.npmjs.com/package/speaking-url-ts)\n[![License](https://img.shields.io/npm/l/speaking-url-ts.svg)](https://github.com/2wce/speaking-url-ts/blob/main/LICENSE)\n![Build Status](https://github.com/2wce/speaking-url-ts/actions/workflows/release.yml/badge.svg)\n\n**speaking-url-ts** is a flexible, language-agnostic library that generates readable, SEO-friendly slugs for any language. It supports custom transliterations and symbol replacements to create clean, URL-safe slugs.\n\n## **Features**\n- Supports multiple languages with custom language packs.\n- Handles transliterations from non-Latin scripts (e.g., Cyrillic, Arabic).\n- Applies custom replacements.\n- Flexible configuration with custom rules for slug formatting.\n\n## **Installation**\n\nYou can install the `speaking-url-ts` library using npm:\n\n```bash\nnpm install speaking-url-ts\n```\n\n## **Usage**\n\n### **Basic Usage**\n\nTo generate a slug, first import the library and then use the `generateSlug` function:\n\n```typescript\nimport { generateSlug, addLanguagePack } from 'speaking-url-ts';\n\n// Use the default English language pack\nconst slug = generateSlug('Hello, World!', { locale: 'en' });\nconsole.log(slug);  // Output: \"hello-world\"\n```\n\n### **Adding a Custom Language Pack**\n\nYou can add a custom language pack to handle specific transliterations, symbol replacements and custom rules for your desired language.\n\nHere’s how to create and add a custom language pack:\n\n1. **Define Your Language Pack**\n\n```javascript\nconst { LanguagePack } = require('speaking-url-ts');\n\nconst customLanguagePack = {\n    transliterations: {\n        '你好': 'nihao',    // Example: Chinese characters to Pinyin\n        'мир': 'mir',       // Example: Russian to Latin\n    },\n    symbols: {\n        '\u0026': 'and',\n        '@': 'at',\n        '%': 'percent',\n    },\n    customRules: [\n        (text) =\u003e text.replace(/м/g, 'm'), // Example: Replace all 'м' with 'm'\n        (text) =\u003e text.trim(), // Trim spaces\n    ]\n};\n```\n\n2. **Add the Language Pack**\n\n```javascript\naddLanguagePack('custom', customLanguagePack);\n```\n\n3. **Generate a Slug Using the Custom Language Pack**\n\n```javascript\nconst slug = generateSlug('Привет, мир!', { locale: 'custom' });\nconsole.log(slug);  // Output: \"privet-mir\"\n```\n\n### **Complete Example**\n\n```typescript\nimport { generateSlug, addLanguagePack } from 'speaking-url-ts';\n\n// Define and add the custom language pack\nconst russianLanguagePack = {\n    transliterations: {\n        'Привет': 'Privet',\n        'мир': 'mir',\n        'й': 'i',\n    },\n    symbols: {\n        '\u0026': 'i',\n        ',': '',\n    },\n    customRules: [\n        text =\u003e text.replace(/м/g, 'm'), // Custom rule to replace 'м' with 'm'\n    ]\n};\n\naddLanguagePack('ru', russianLanguagePack);\n\n// Generate a slug\nconst slug = generateSlug('Привет, мир и Москва', { locale: 'ru' });\nconsole.log(slug);  // Output: \"privet-mir-i-moskva\"\n```\n\n## **API Reference**\n\n### **`generateSlug(input: string, options: { locale: string, separator?: string }): string`**\n\nGenerates a slug from the input string.\n\n- **`input`**: The text to be converted into a slug.\n- **`options`**:\n  - **`locale`**: The language pack to use (e.g., `'en'` for English).\n  - **`separator`**: (Optional) The character used to separate words in the slug. Defaults to `'-'`.\n\n### **`addLanguagePack(locale: string, pack: LanguagePack): void`**\n\nAdds a new language pack or updates an existing one.\n\n- **`locale`**: The locale identifier (e.g., `'ru'` for Russian).\n- **`pack`**: The language pack object containing transliterations, replacements, stop words, and custom rules.\n\n## **Language Pack Structure**\n\nA language pack is an object with the following optional fields:\n\n- **`transliterations`**: An object mapping characters or phrases to their transliterated equivalents.\n- **`symbols`**: An object mapping characters to replace.\n- **`customRules`**: An array of functions that apply custom transformations to the text.\n\n### **Example Language Pack**\n\n```typescript\ninterface LanguagePack {\n    transliterations?: { [key: string]: string };\n    symbols?: { [key: string]: string };\n    customRules?: Array\u003c(text: string) =\u003e string\u003e;\n}\n```\n\n### **Contributing**\n\nContributions are welcome! Please fork the repository, create a new branch, and submit a pull request with your improvements or new language packs.\n\n## **License**\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2wce%2Fspeaking-url-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F2wce%2Fspeaking-url-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2wce%2Fspeaking-url-ts/lists"}