i18n-iso-cities 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 houssam966
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# i18n-iso-cities
+
+Multilingual city name translations organized by ISO 3166-1 alpha-2 country codes.  
+Modeled after [i18n-iso-countries](https://www.npmjs.com/package/i18n-iso-countries) — register only the locales you need for tree-shaking.
+
+## Installation
+
+```bash
+npm install i18n-iso-cities
+```
+
+## Usage
+
+```js
+import cities from 'i18n-iso-cities';
+
+// Import only the locales you need (tree-shakeable)
+import en from 'i18n-iso-cities/langs/en.json';
+import ar from 'i18n-iso-cities/langs/ar.json';
+
+cities.registerLocale(en);
+cities.registerLocale(ar);
+```
+
+### Translate a city name (with country code)
+
+```js
+cities.getName('SA', 'Riyadh', 'ar');   // 'الرياض'
+cities.getName('AE', 'Dubai', 'ar');     // 'دبي'
+cities.getName('EG', 'Cairo', 'ar');     // 'القاهرة'
+cities.getName('US', 'New York', 'ar');  // 'نيويورك'
+```
+
+### Translate without country code (convenience)
+
+Useful when you get city names from APIs (e.g. Instagram demographics) without country codes.
+
+```js
+cities.translate('Riyadh', 'ar');  // 'الرياض'
+cities.translate('london', 'ar');  // 'لندن'  (case-insensitive)
+```
+
+### Get all cities for a country
+
+```js
+cities.getAll('QA', 'ar');
+// [
+//   { name: 'Al Daayen', translation: 'الضعاين' },
+//   { name: 'Al Khor', translation: 'الخور' },
+//   { name: 'Al Rayyan', translation: 'الريان' },
+//   { name: 'Al Shamal', translation: 'الشمال' },
+//   { name: 'Al Wakrah', translation: 'الوكرة' },
+//   { name: 'Doha', translation: 'الدوحة' },
+//   ...
+// ]
+```
+
+### Reverse lookup (translated → original)
+
+```js
+cities.getOriginalName('الرياض', 'ar');
+// { countryCode: 'SA', name: 'Riyadh' }
+```
+
+### Utility methods
+
+```js
+cities.getCountryCodes('ar');      // ['SA', 'AE', 'KW', 'QA', ...]
+cities.getSupportedLocales();      // ['en', 'ar']
+```
+
+## Supported Locales
+
+| Locale | Language |
+|--------|----------|
+| `en`   | English  |
+| `ar`   | Arabic   |
+
+## Covered Countries
+
+### Arab World (comprehensive coverage)
+🇸🇦 Saudi Arabia (70+ cities) · 🇦🇪 UAE · 🇰🇼 Kuwait · 🇶🇦 Qatar · 🇧🇭 Bahrain · 🇴🇲 Oman  
+🇵🇸 Palestine · 🇯🇴 Jordan · 🇪🇬 Egypt · 🇱🇧 Lebanon · 🇮🇶 Iraq · 🇱🇾 Libya  
+🇸🇩 Sudan · 🇲🇦 Morocco · 🇹🇳 Tunisia · 🇩🇿 Algeria · 🇸🇾 Syria · 🇾🇪 Yemen
+
+### Major World Cities
+🇬🇧 United Kingdom · 🇺🇸 United States · 🇫🇷 France · 🇩🇪 Germany · 🇹🇷 Turkey · 🇮🇳 India · 🇵🇰 Pakistan
+
+## Contributing
+
+### Adding a new locale
+
+1. Create `langs/<locale>.json` following the existing format:
+
+```json
+{
+  "locale": "fr",
+  "cities": {
+    "SA": {
+      "Riyadh": "Riyad",
+      "Jeddah": "Djeddah"
+    }
+  }
+}
+```
+
+2. The keys must match the English city names in `langs/en.json`.
+3. Submit a pull request.
+
+### Adding cities
+
+1. Add the city to **all** locale files (`en.json`, `ar.json`, etc.).
+2. Keep cities alphabetically sorted within each country.
+3. Run `npm test` to verify data integrity.
+
+## API Reference
+
+### `registerLocale(data: LocaleData): void`
+Register a locale. Must be called before using other methods.
+
+### `getName(countryCode: string, cityName: string, locale: string): string | undefined`
+Get translated city name by country code and English name.
+
+### `translate(cityName: string, locale: string): string | undefined`
+Translate a city name without specifying country code (case-insensitive, first match).
+
+### `getAll(countryCode: string, locale: string): CityEntry[]`
+Get all cities for a country, sorted by English name.
+
+### `getOriginalName(translatedName: string, locale: string): CityLookup | undefined`
+Reverse lookup: translated name → `{ countryCode, name }`.
+
+### `getCountryCodes(locale: string): string[]`
+Get all country codes that have data for a locale.
+
+### `getSupportedLocales(): string[]`
+Get all registered locale codes.
+
+## License
+
+MIT © [houssam966](https://github.com/houssam966)

package/dist/index.d.mts

@@ -0,0 +1,91 @@
+/**
+ * i18n-iso-cities
+ *
+ * Multilingual city name translations organized by ISO 3166-1 country codes.
+ * Modeled after i18n-iso-countries — register only the locales you need.
+ *
+ * Usage:
+ *   import cities from 'i18n-iso-cities';
+ *   import en from 'i18n-iso-cities/langs/en.json';
+ *   import ar from 'i18n-iso-cities/langs/ar.json';
+ *
+ *   cities.registerLocale(en);
+ *   cities.registerLocale(ar);
+ *
+ *   cities.getName('SA', 'Riyadh', 'ar');        // 'الرياض'
+ *   cities.translate('Riyadh', 'ar');             // 'الرياض'
+ *   cities.getAll('SA', 'ar');                    // [{ name: 'Riyadh', translation: 'الرياض' }, ...]
+ *   cities.getOriginalName('الرياض', 'ar');        // { countryCode: 'SA', name: 'Riyadh' }
+ */
+interface LocaleData {
+    locale: string;
+    cities: Record<string, Record<string, string>>;
+}
+interface CityEntry {
+    name: string;
+    translation: string;
+}
+interface CityLookup {
+    countryCode: string;
+    name: string;
+}
+/**
+ * Register a locale. Call this once per locale before using other methods.
+ * Locales are tree-shakeable — only import the ones you need.
+ */
+declare function registerLocale(data: LocaleData): void;
+/**
+ * Get the translated name of a city in a specific country.
+ *
+ * @param countryCode - ISO 3166-1 alpha-2 country code (e.g. "SA")
+ * @param cityName    - English city name (e.g. "Riyadh")
+ * @param locale      - Target locale (e.g. "ar")
+ * @returns Translated city name, or undefined if not found
+ */
+declare function getName(countryCode: string, cityName: string, locale: string): string | undefined;
+/**
+ * Translate a city name without specifying a country code.
+ * Searches all registered countries in the locale; returns first match.
+ * Useful for translating raw API responses (e.g. Instagram demographics).
+ *
+ * @param cityName - English city name (case-insensitive)
+ * @param locale   - Target locale
+ * @returns Translated name, or undefined
+ */
+declare function translate(cityName: string, locale: string): string | undefined;
+/**
+ * Get all cities for a country in a given locale.
+ *
+ * @param countryCode - ISO 3166-1 alpha-2 code
+ * @param locale      - Target locale
+ * @returns Array of { name, translation } objects sorted by English name
+ */
+declare function getAll(countryCode: string, locale: string): CityEntry[];
+/**
+ * Reverse-lookup: given a translated city name, find the original English name
+ * and country code.
+ *
+ * @param translatedName - City name in the target locale (e.g. "الرياض")
+ * @param locale         - The locale of the translated name
+ * @returns { countryCode, name } or undefined
+ */
+declare function getOriginalName(translatedName: string, locale: string): CityLookup | undefined;
+/**
+ * Get all country codes that have city data for a given locale.
+ */
+declare function getCountryCodes(locale: string): string[];
+/**
+ * Get all registered locales.
+ */
+declare function getSupportedLocales(): string[];
+declare const _default: {
+    registerLocale: typeof registerLocale;
+    getName: typeof getName;
+    translate: typeof translate;
+    getAll: typeof getAll;
+    getOriginalName: typeof getOriginalName;
+    getCountryCodes: typeof getCountryCodes;
+    getSupportedLocales: typeof getSupportedLocales;
+};
+
+export { type CityEntry, type CityLookup, type LocaleData, _default as default, getAll, getCountryCodes, getName, getOriginalName, getSupportedLocales, registerLocale, translate };

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * i18n-iso-cities
+ *
+ * Multilingual city name translations organized by ISO 3166-1 country codes.
+ * Modeled after i18n-iso-countries — register only the locales you need.
+ *
+ * Usage:
+ *   import cities from 'i18n-iso-cities';
+ *   import en from 'i18n-iso-cities/langs/en.json';
+ *   import ar from 'i18n-iso-cities/langs/ar.json';
+ *
+ *   cities.registerLocale(en);
+ *   cities.registerLocale(ar);
+ *
+ *   cities.getName('SA', 'Riyadh', 'ar');        // 'الرياض'
+ *   cities.translate('Riyadh', 'ar');             // 'الرياض'
+ *   cities.getAll('SA', 'ar');                    // [{ name: 'Riyadh', translation: 'الرياض' }, ...]
+ *   cities.getOriginalName('الرياض', 'ar');        // { countryCode: 'SA', name: 'Riyadh' }
+ */
+interface LocaleData {
+    locale: string;
+    cities: Record<string, Record<string, string>>;
+}
+interface CityEntry {
+    name: string;
+    translation: string;
+}
+interface CityLookup {
+    countryCode: string;
+    name: string;
+}
+/**
+ * Register a locale. Call this once per locale before using other methods.
+ * Locales are tree-shakeable — only import the ones you need.
+ */
+declare function registerLocale(data: LocaleData): void;
+/**
+ * Get the translated name of a city in a specific country.
+ *
+ * @param countryCode - ISO 3166-1 alpha-2 country code (e.g. "SA")
+ * @param cityName    - English city name (e.g. "Riyadh")
+ * @param locale      - Target locale (e.g. "ar")
+ * @returns Translated city name, or undefined if not found
+ */
+declare function getName(countryCode: string, cityName: string, locale: string): string | undefined;
+/**
+ * Translate a city name without specifying a country code.
+ * Searches all registered countries in the locale; returns first match.
+ * Useful for translating raw API responses (e.g. Instagram demographics).
+ *
+ * @param cityName - English city name (case-insensitive)
+ * @param locale   - Target locale
+ * @returns Translated name, or undefined
+ */
+declare function translate(cityName: string, locale: string): string | undefined;
+/**
+ * Get all cities for a country in a given locale.
+ *
+ * @param countryCode - ISO 3166-1 alpha-2 code
+ * @param locale      - Target locale
+ * @returns Array of { name, translation } objects sorted by English name
+ */
+declare function getAll(countryCode: string, locale: string): CityEntry[];
+/**
+ * Reverse-lookup: given a translated city name, find the original English name
+ * and country code.
+ *
+ * @param translatedName - City name in the target locale (e.g. "الرياض")
+ * @param locale         - The locale of the translated name
+ * @returns { countryCode, name } or undefined
+ */
+declare function getOriginalName(translatedName: string, locale: string): CityLookup | undefined;
+/**
+ * Get all country codes that have city data for a given locale.
+ */
+declare function getCountryCodes(locale: string): string[];
+/**
+ * Get all registered locales.
+ */
+declare function getSupportedLocales(): string[];
+declare const _default: {
+    registerLocale: typeof registerLocale;
+    getName: typeof getName;
+    translate: typeof translate;
+    getAll: typeof getAll;
+    getOriginalName: typeof getOriginalName;
+    getCountryCodes: typeof getCountryCodes;
+    getSupportedLocales: typeof getSupportedLocales;
+};
+
+export { type CityEntry, type CityLookup, type LocaleData, _default as default, getAll, getCountryCodes, getName, getOriginalName, getSupportedLocales, registerLocale, translate };

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  getAll: () => getAll,
+  getCountryCodes: () => getCountryCodes,
+  getName: () => getName,
+  getOriginalName: () => getOriginalName,
+  getSupportedLocales: () => getSupportedLocales,
+  registerLocale: () => registerLocale,
+  translate: () => translate
+});
+module.exports = __toCommonJS(index_exports);
+var locales = {};
+var reverseCache = {};
+var flatCache = {};
+function invalidateCache(locale) {
+  delete reverseCache[locale];
+  delete flatCache[locale];
+}
+function ensureReverse(locale) {
+  if (!reverseCache[locale]) {
+    const map = /* @__PURE__ */ new Map();
+    const countries = locales[locale];
+    if (countries) {
+      for (const [countryCode, cityMap] of Object.entries(countries)) {
+        for (const [name, translation] of Object.entries(cityMap)) {
+          if (!map.has(translation)) {
+            map.set(translation, { countryCode, name });
+          }
+        }
+      }
+    }
+    reverseCache[locale] = map;
+  }
+  return reverseCache[locale];
+}
+function ensureFlat(locale) {
+  if (!flatCache[locale]) {
+    const map = /* @__PURE__ */ new Map();
+    const countries = locales[locale];
+    if (countries) {
+      for (const cityMap of Object.values(countries)) {
+        for (const [name, translation] of Object.entries(cityMap)) {
+          const key = name.toLowerCase();
+          if (!map.has(key)) {
+            map.set(key, translation);
+          }
+        }
+      }
+    }
+    flatCache[locale] = map;
+  }
+  return flatCache[locale];
+}
+function registerLocale(data) {
+  if (!data?.locale || !data?.cities) return;
+  locales[data.locale] = data.cities;
+  invalidateCache(data.locale);
+}
+function getName(countryCode, cityName, locale) {
+  return locales[locale]?.[countryCode.toUpperCase()]?.[cityName];
+}
+function translate(cityName, locale) {
+  if (!cityName) return void 0;
+  return ensureFlat(locale).get(cityName.toLowerCase());
+}
+function getAll(countryCode, locale) {
+  const cityMap = locales[locale]?.[countryCode.toUpperCase()];
+  if (!cityMap) return [];
+  return Object.entries(cityMap).map(([name, translation]) => ({ name, translation })).sort((a, b) => a.name.localeCompare(b.name));
+}
+function getOriginalName(translatedName, locale) {
+  if (!translatedName) return void 0;
+  return ensureReverse(locale).get(translatedName);
+}
+function getCountryCodes(locale) {
+  return Object.keys(locales[locale] ?? {});
+}
+function getSupportedLocales() {
+  return Object.keys(locales);
+}
+var index_default = {
+  registerLocale,
+  getName,
+  translate,
+  getAll,
+  getOriginalName,
+  getCountryCodes,
+  getSupportedLocales
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAll,
+  getCountryCodes,
+  getName,
+  getOriginalName,
+  getSupportedLocales,
+  registerLocale,
+  translate
+});

package/dist/index.mjs

@@ -0,0 +1,89 @@
+// src/index.ts
+var locales = {};
+var reverseCache = {};
+var flatCache = {};
+function invalidateCache(locale) {
+  delete reverseCache[locale];
+  delete flatCache[locale];
+}
+function ensureReverse(locale) {
+  if (!reverseCache[locale]) {
+    const map = /* @__PURE__ */ new Map();
+    const countries = locales[locale];
+    if (countries) {
+      for (const [countryCode, cityMap] of Object.entries(countries)) {
+        for (const [name, translation] of Object.entries(cityMap)) {
+          if (!map.has(translation)) {
+            map.set(translation, { countryCode, name });
+          }
+        }
+      }
+    }
+    reverseCache[locale] = map;
+  }
+  return reverseCache[locale];
+}
+function ensureFlat(locale) {
+  if (!flatCache[locale]) {
+    const map = /* @__PURE__ */ new Map();
+    const countries = locales[locale];
+    if (countries) {
+      for (const cityMap of Object.values(countries)) {
+        for (const [name, translation] of Object.entries(cityMap)) {
+          const key = name.toLowerCase();
+          if (!map.has(key)) {
+            map.set(key, translation);
+          }
+        }
+      }
+    }
+    flatCache[locale] = map;
+  }
+  return flatCache[locale];
+}
+function registerLocale(data) {
+  if (!data?.locale || !data?.cities) return;
+  locales[data.locale] = data.cities;
+  invalidateCache(data.locale);
+}
+function getName(countryCode, cityName, locale) {
+  return locales[locale]?.[countryCode.toUpperCase()]?.[cityName];
+}
+function translate(cityName, locale) {
+  if (!cityName) return void 0;
+  return ensureFlat(locale).get(cityName.toLowerCase());
+}
+function getAll(countryCode, locale) {
+  const cityMap = locales[locale]?.[countryCode.toUpperCase()];
+  if (!cityMap) return [];
+  return Object.entries(cityMap).map(([name, translation]) => ({ name, translation })).sort((a, b) => a.name.localeCompare(b.name));
+}
+function getOriginalName(translatedName, locale) {
+  if (!translatedName) return void 0;
+  return ensureReverse(locale).get(translatedName);
+}
+function getCountryCodes(locale) {
+  return Object.keys(locales[locale] ?? {});
+}
+function getSupportedLocales() {
+  return Object.keys(locales);
+}
+var index_default = {
+  registerLocale,
+  getName,
+  translate,
+  getAll,
+  getOriginalName,
+  getCountryCodes,
+  getSupportedLocales
+};
+export {
+  index_default as default,
+  getAll,
+  getCountryCodes,
+  getName,
+  getOriginalName,
+  getSupportedLocales,
+  registerLocale,
+  translate
+};