{"id":19335229,"url":"https://github.com/wp-blocks/isotolanguage","last_synced_at":"2025-04-23T00:31:54.305Z","repository":{"id":212670571,"uuid":"732036731","full_name":"wp-blocks/ISOToLanguage","owner":"wp-blocks","description":" It turns ISO-Codes into country / language names effortlessly, giving you the essentials minus the fluff. Let the ISO fun begin! 🌍✨","archived":false,"fork":false,"pushed_at":"2024-06-01T12:31:27.000Z","size":691,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-21T20:06:28.711Z","etag":null,"topics":["country","country-code","ietf","iso","language","language-tag","locale-format"],"latest_commit_sha":null,"homepage":"https://wp-blocks.github.io/ISOToLanguage/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wp-blocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-15T13:36:22.000Z","updated_at":"2024-11-18T02:51:32.000Z","dependencies_parsed_at":"2024-05-13T19:00:15.342Z","dependency_job_id":null,"html_url":"https://github.com/wp-blocks/ISOToLanguage","commit_stats":null,"previous_names":["erikyo/isotolanguage"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2FISOToLanguage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2FISOToLanguage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2FISOToLanguage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wp-blocks%2FISOToLanguage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wp-blocks","download_url":"https://codeload.github.com/wp-blocks/ISOToLanguage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250348290,"owners_count":21415893,"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":["country","country-code","ietf","iso","language","language-tag","locale-format"],"created_at":"2024-11-10T03:06:31.795Z","updated_at":"2025-04-23T00:31:53.863Z","avatar_url":"https://github.com/wp-blocks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ISO To Language\n\n\u003cdiv\u003e\n  \u003ca href=\"https://www.npmjs.com/package/isotolanguage\"\u003e\n    \u003cimg alt=\"version\" src=\"https://img.shields.io/npm/v/isotolanguage.svg?label=npm%20version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/wp-blocks/isotolanguage/blob/master/LICENSE\"\u003e\n    \u003cimg alt=\"version\" src=\"https://img.shields.io/npm/l/isotolanguage\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/wp-blocks/ISOToLanguage/actions\"\u003e\n    \u003cimg alt=\"build\" src=\"https://img.shields.io/github/actions/workflow/status/wp-blocks/ISOToLanguage/pnpm.yml\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/wp-blocks/ISOToLanguage/actions\"\u003e\n    \u003cimg alt=\"workflows\" src=\"https://github.com/wp-blocks/ISOToLanguage/actions/workflows/pnpm.yml/badge.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\nUnlock the power of ISO codes with our lightweight and high-performance ISO-to-language converter module. This meticulously crafted package seamlessly transforms ISO country and language codes into meaningful country names, ensuring you\nhave all the essentials without unnecessary bloat.\n\nGet information for each iso code, our dataset is one of the most complete we have original and international name, iso2 and 3, flags, tld, currency, dial, continent, sub-region and more take a look below, you will be amazed at the amount of data available\n\n\n## Key Features:\n\n- **🚀 Performance-Driven:** Engineered with speed in mind, the package boasts swift execution for seamless integration into your projects.\n\n- **📦 Minimal Footprint:** Weighing less than 40kb gzipped, no dependencies, it keeps your project light without compromising on functionality.\n\n- **🎯 Focused Functionality:** From validating ISO codes to formatting languages and countries, our module provides a suite of versatile utility functions for your language-related tasks.\n\n- **📒 Well-Defined Types:** Utilizes TypeScript for well-documented and type-safe development.\n\n- **✅ Tested:** Comprehensive Jest tests with 100% coverage to ensure reliability.\n\n# Usage\n\n### As a browser script\n\nBrowser:\n\n```html\n\u003chead\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/isotolanguage@1.0.1/lib/browser/isoToLanguage.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cdiv id=\"lang\"\u003e\u003c/div\u003e\n\u003cscript\u003edocument.querySelector('#lang').innerHTML = JSON.stringify(isoToLanguage.getAll())\u003c/script\u003e\n```\n\nUmd:\n\n```html\n\u003cscript src=\"./node_modules/isoToLanguage/lib/umd/isoToLanguage.js\"\u003e\u003c/script\u003e\n\u003cscript\u003edocument.querySelector('#lang').innerHTML = JSON.stringify(isoToLanguage.getAll())\u003c/script\u003e\n```\n\n\n### As Module\n\n#### Installation\n\nInstall the module using npm:\n\n```bash\nnpm install ISOToLanguage\n```\n\nCommon JS (require):\n\n```javascript\nconst ITL = require('ISOToLanguage');\nconsole.log(ITL.getAll());\n```\n\nESM import:\n\n```javascript\nimport ITL from 'ISOToLanguage';\n// or\nimport { getCountry, getAll } from 'ISOToLanguage';\n```\n\n## Functions\n\n1. **[validateISO](#validateISO)**\n   Validates ISO codes for countries.\n\n2. **[isoInfo](#isoInfo)**\n   Decrypts an iso code of type language, country, local, or language-code\n\n3. **[formatIso](#isoFormat)**\n    Formats language and country into a single string.\n\n4. **[getIso](#getIso)**\n    Retrieves data by ISO code and a specific type.\n\n5. **[getAll](#getAll)**\n   Retrieves data based on a specified type.\n\n6. **[getGroupedBy](#getGroupedBy)**\n   Builds an object of country data grouped by a custom field\n\n7. **[getKeyValue](#getKeyValue)**\n   Generates an array with the given key value combination.\n\n8. **[getCountriesByLanguage](#getCountriesByLanguage)**\n   Returns countries that speak any of the given languages.\n\n9. **[getByProximity](#getByProximity)**\n   Retrieves a list of countries within a specified proximity of the given country.\n\n---\n\n## `isoInfo`\n\nA function that formats the language and country into a single string.\n\n**Args**: `{ \"codeType\": \"language-iso2\" | \"language-iso3\" | \"country-iso\" | \"locale\" | \"language-code\" }`\n\n```javascript\nconst result = isoInfo('it');\nconsole.log(result); // { \"name\": \"Italian\", \"original\": \"Italiano\", \"iso3\": \"ita\", \"iso2\": \"it\" }\n```\n\n```javascript\nconst result = isoInfo('IT');\nconsole.log(result); // { \"iso2\": \"IT\", \"languages\": [ \"it\" ], \"name\": \"Italy\", \"original\": \"Italia\", \"iso3\": \"ITA\" }\n```\n\n```javascript\nconst result = isoInfo('ITA');\nconsole.log(result); // { \"languages\": [ \"it\" ], \"name\": \"Italy\", \"original\": \"Italia\", \"iso3\": \"ITA\" }\n```\n\n```javascript\nconst result = isoInfo('it_IT');\nconsole.log(result); // { \"type\": \"locale\", \"country\": {...}, \"language\": {...} }\n```\n\n```javascript\nconst result = isoInfo('it-IT');\nconsole.log(result); // { \"type\": \"language-code\", \"country\": {...}, \"language\": {...} }\n```\n\n\n## `formatIso`\n\nA function that formats the language and country into a single string.\n\n**Args**: `{ \"arg1\": \"language\", \"arg2?\": \"iso\", \"arg3?\": {\"type\": IsoDataType, \"separator\": string } }`\n\n```javascript\nconst result = formatIso('en', 'us');\nconsole.log(result); // en_US\n```\n\n```javascript\nconst result = formatIso('en', 'US', { separator: '-' });\nconsole.log(result); // en-US\n```\n\n```javascript\nconst result = formatIso('en', 'US', { type: 'language-code' });\nconsole.log(result); // en-US\n```\n\n```javascript\nconst result = formatIso('en', 'US', { type: 'locale' });\nconsole.log(result); // en_US\n```\n\n## `getIso`\n\nReturns the information about the iso code\n\n**Args**: `{ \"key\": iso2 | iso3 | country | country name | original country name, \"type?\": country | language, \"field\": [arrayOfFields] }`\n\n```javascript\nconst isoArray = getIso('GB');\nconsole.log(isoArray);\n\n/*\n  { \"iso2\": \"GB\", \"languages\": [ \"en\" ], \"name\": \"United Kingdom\", \"original\": \"United Kingdom\", \"iso3\": \"GBR\" }\n*/\n```\n```javascript\nconst isoArray = getIso('Italiano', 'language');\nconsole.log(isoArray);\n\n/*\n  { \"name\": \"Italian\", \"original\": \"Italiano\", \"iso3\": \"ita\", \"iso2\": \"it\" }\n*/\n```\n```javascript\nconst isoArray = getIso('Italiano', 'language', 'iso2');\nconsole.log(isoArray);\n\n/* it */\n```\n```javascript\nconst isoArray = getIso('Italia', 'country', 'flag');\nconsole.log(isoArray);\n\n/* https://upload.wikimedia.org/wikipedia/commons/0/03/Flag_of_Italy.svg */\n```\n```javascript\nconst isoArray = getIso('Tunisia', \"country\", ['capital', 'currency']);\nconsole.log(isoArray);\n\n/*\n{\n  \"capital\": \"Tunis\",\n  \"currency\": {\n    \"code\": \"TND\",\n    \"symbol\": \"DT\",\n    \"original\": \"د.ت.‏\",\n    \"name\": \"Tunisian Dinar\"\n  }\n}\n*/\n```\n```javascript\nconst isoArray = getIso('Spain', undefined, ['name', 'locale', 'language-code']);\nconsole.log(isoArray);\n\n/*\n{\n  \"name\": \"Spain\",\n  \"locale\": [\n    \"es_ES\",\n    \"eu_ES\",\n    \"ca_ES\",\n    \"gl_ES\",\n    \"oc_ES\"\n  ],\n  \"language-code\": [\n    \"es-ES\",\n    \"eu-ES\",\n    \"ca-ES\",\n    \"gl-ES\",\n    \"oc-ES\"\n  ]\n}\n*/\n```\n\n\n\n## `getAll`\n\nGet all data for all countries, accept the type 'iso' | 'languages' | 'name' | 'original' | 'language-code' | 'language-name' | 'language-original' | 'locale'\n\n**Args**: `{ \"type?\": IsoDataType }`\n\n```javascript\nconst allData = getAll();\nconsole.log(allData);\n\n/*\n{\n  \"AD\": {\n    \"languages\": [\"ca\"],\n    \"name\": \"Andorra\",\n    \"original\": \"Andorra\"\n  },\n  \"AE\": {\n    \"languages\": [\"ar\"],\n    \"name\": \"United Arab Emirates\",\n    \"original\": \"دولة الإمارات العربية المتحدة\"\n  },\n  ...\n}\n*/\n```\n```javascript\nconst isoArray = getAll('iso');\nconsole.log(isoArray);\n\n/*\n  [\"AD\", \"AE\", \"AF\", \"AG\", \"AI\", \"AL\", \"AM\", \"AO\", \"AQ\", \"AR\", \"AS\", \"AT\", \"AU\", \"AW\", ...]\n*/\n```\n```javascript\nconst languageCodesArray = getAll('language-codes');\nconsole.log(languageCodesArray);\n\n/*\n  [\"ca-AD\", \"ar-AE\", \"ps-AF\", \"uz-AF\", \"tk-AF\", \"en-AG\", \"en-AI\", \"sq-AL\", \"hy-AM\", \"ru-AM\", \"pt-AO\", \"es-AR\", \"gn-AR\", \"en-AS\", ...]\n*/\n```\n\n\n## `getGroupedBy`\n\nYou can group the results by continent or region or subRegion. Pass a second argument to filter by that term.\n\n**Args**: `{ \"type?\": \"continent\" | \"region\" | \"subRegion\" }`\n\n```javascript\nconst allData = getGroupedBy( 'continent' );\nconsole.log(allData);\n/*\n{\n  \"EU\": {\n    \"AX\": {\n      \"name\": \"Aland\",\n      (...)\n    },\n    \"AL\": {\n      \"name\": \"Albania\",\n      (...)\n    },\n    (...)\n  },\n  \"AN\": {\n    \"AQ\": {\n      \"name\": \"Antarctica\",\n  (...)\n}\n*/\n```\n```javascript\nconst allData = getGroupedBy( 'continent', 'Antarctica' );\nconsole.log(allData);\n/*\n{\n  \"Antarctica\": {\n    \"AQ\": {\n      \"languages\": [],\n      \"name\": \"Antarctica\",\n      \"original\": \"Antarctica\",\n      \"iso3\": \"ATA\",\n      \"region\": \"Antarctica\",\n      \"continent\": \"AN\",\n      \"subRegion\": \"Antarctica\"\n    }\n  }\n}\n*/\n```\n\n## `getKeyValue`\n\nReturns an Array with the combination of the given key / value\n\n**Args**: `{ \"key\" : IsoDataType, \"value\" : IsoDataType }`\n\n```javascript\nconst dataAsKey = getKeyValue('language', 'original');\nconsole.log(dataAsKey);\n\n/*\n[\n  {\n    \"label\": \"ca_AD\",\n    \"value\": \"Andorra\"\n  },\n  {\n    \"label\": \"ar_AE\",\n    \"value\": \"دولة الإمارات العربية المتحدة\"\n  },\n  {\n    \"label\": \"ps_AF\",\n    \"value\": \"افغانستان (ps_AF)\"\n  },\n  {\n    \"label\": \"uz_AF\",\n    \"value\": \"افغانستان (uz_AF)\"\n  },\n  {\n    \"label\": \"tk_AF\",\n    \"value\": \"افغانستان (tk_AF)\"\n  },\n(...)\n*/\n```\n\n```javascript\nconst data = getKeyValue( 'locale', 'flag', \"the language locale\", \"flag\" );\nconsole.log(data);\n\n/*\n[\n  {\n    \"the language locale\": \"ca_AD\",\n    \"flag\": \"https://upload.wikimedia.org/wikipedia/commons/1/19/Flag_of_Andorra.svg\"\n  },\n  {\n    \"the language locale\": \"ar_AE\",\n    \"flag\": \"https://upload.wikimedia.org/wikipedia/commons/c/cb/Flag_of_the_United_Arab_Emirates.svg\"\n  },\n  {\n    \"the language locale\": \"ps_AF\",\n    \"flag\": \"https://upload.wikimedia.org/wikipedia/commons/5/5c/Flag_of_the_Taliban.svg (ps_AF)\"\n  },\n(...)\n*/\n```\n\n## `getCountriesByLanguage`\n\nReturns all the countries of the specified languages\n\n**Args**: `{ \"languages\" : [arrayOfLanguages] }`\n\n```javascript\nconst dataAsKey = getCountriesByLanguage(['it', 'es']);\nconsole.log(dataAsKey);\n/*\n{\n  \"AR\": {\n    \"languages\": [\n      \"es\",\n      \"gn\"\n    ],\n    \"name\": \"Argentina\",\n    \"original\": \"Argentina\",\n    \"iso3\": \"ARG\"\n  },\n  (...)\n  \"CH\": {\n    \"languages\": [\n      \"de\",\n      \"fr\",\n      \"it\"\n    ],\n    \"name\": \"Switzerland\",\n    \"original\": \"Schweiz\",\n    \"iso3\": \"CHE\"\n  },\n(...)\n*/\n```\n\n## `getByProximity`\n\nRetrieves a list of countries within a specified range from the center of the given country.\n\n**Args**: `{ \"languages\" : [arrayOfLanguages] }`\n\n```javascript\nconst dataAsKey = getByProximity('it', 1000);\nconsole.log(dataAsKey);\n\n/*\n[\n    { iso: 'IT', coordinates: [ 41.8719, 12.5674 ], distance: 0 },\n    {\n        iso: 'VA',\n        coordinates: [ 41.9029, 12.4534 ],\n        distance: 10.04676735128846\n    },\n    {\n        iso: 'SM',\n        coordinates: [ 43.9424, 12.4578 ],\n        distance: 230.40201087435003\n    },\n    {\n        iso: 'HR',\n        coordinates: [ 45.1, 15.2 ],\n        distance: 417.01956518047405\n    },\n    {\n        iso: 'MC',\n        coordinates: [ 43.7503, 7.4128 ],\n        distance: 469.37405276643517\n    },\n    {\n        iso: 'BA',\n        coordinates: [ 43.9159, 17.6791 ],\n        distance: 474.2778009042667\n    },\n    {\n        iso: 'SI',\n        coordinates: [ 46.1512, 14.9955 ],\n        distance: 513.8640413087771\n    },\n    {\n        iso: 'ME',\n        coordinates: [ 42.7087, 19.3744 ],\n        distance: 567.4303782156377\n    },\n    {\n        iso: 'LI',\n        coordinates: [ 47.166, 9.5554 ],\n        distance: 635.1401466708603\n    },\n    {\n        iso: 'AL',\n        coordinates: [ 41.1533, 20.1683 ],\n        distance: 637.6883921375974\n    },\n    {\n        iso: 'AT',\n        coordinates: [ 47.5162, 14.5501 ],\n        distance: 646.8280352835117\n    },\n    {\n        iso: 'CH',\n        coordinates: [ 46.8182, 8.2275 ],\n        distance: 649.0693011095187\n    },\n    {\n        iso: 'MT',\n        coordinates: [ 35.9375, 14.3754 ],\n        distance: 678.1192634942938\n    },\n    {\n        iso: 'XK',\n        coordinates: [ 42.6026, 20.903 ],\n        distance: 690.7348154830586\n    },\n    {\n        iso: 'RS',\n        coordinates: [ 44.0165, 21.0059 ],\n        distance: 726.6754233126602\n    },\n    {\n        iso: 'MK',\n        coordinates: [ 41.6086, 21.7453 ],\n        distance: 761.6932798987688\n    },\n    {\n        iso: 'HU',\n        coordinates: [ 47.1625, 19.5033 ],\n        distance: 804.6598779515814\n    },\n    {\n        iso: 'GR',\n        coordinates: [ 39.0742, 21.8243 ],\n        distance: 841.9857682997398\n    },\n    {\n        iso: 'AD',\n        coordinates: [ 42.5462, 1.6016 ],\n        distance: 905.6320231312061\n    },\n    {\n        iso: 'CZ',\n        coordinates: [ 49.8175, 15.473 ],\n        distance: 911.5367886248189\n    },\n    {\n        iso: 'TN',\n        coordinates: [ 33.8869, 9.5375 ],\n        distance: 926.6812884937063\n    },\n    {\n        iso: 'SK',\n        coordinates: [ 48.669, 19.699 ],\n        distance: 938.6194450746992\n    },\n    {\n        iso: 'FR',\n        coordinates: [ 46.2276, 2.2137 ],\n        distance: 957.6636949908722\n    }\n]\n*/\n```\n\n## A brief recap\n\n### ISO Country Code\n\nISO 3166-1-alpha-2 is the standard for country codes. It defines two-letter codes that are unique to each country. For example, the country code for the United Kingdom is `GB`, the country code for France is `FR`, and the country code for\nSpain is `ES`.\n\n### Language Code\n\nISO 639 is the standard for language codes. It defines two-letter and three-letter codes that are unique to each language. For example, the two-letter language code for English is `en`, the two-letter language code for French is `fr`, and\nthe two-letter language code for Spanish is `es`.\n\n## Locale Format\n\nThe locale formatIso is a way of combining a language code and a country code to represent a specific linguistic and cultural context. There are two main locale formats:\n\n### BCP 47 (IETF language tag):\n\nThe BCP 47 formatIso separates the language code and country code with an underscore. For example, `en_US` represents English spoken in the United States, `fr_FR` represents French spoken in France, and `es_ES` represents Spanish spoken in\nSpain.\n\n### ISO 3166-1-alpha-2 or language code:\n\nThe ISO 3166-1-alpha-2 formatIso uses the ISO 3166-1-alpha-2 country code instead of an underscore. For example, `en-US` represents English spoken in the United States, `fr-FR` represents French spoken in France, and `es-ES` represents Spanish\nspoken in Spain.\n\n## Contributing\n\nFeel free to contribute by opening issues or submitting pull requests.\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%2Fwp-blocks%2Fisotolanguage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwp-blocks%2Fisotolanguage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwp-blocks%2Fisotolanguage/lists"}