intl-tel-input 21.1.3 → 21.2.0

package/README.md

@@ -1,10 +1,12 @@
 # International Telephone Input [![Build Status](https://app.travis-ci.com/jackocnr/intl-tel-input.svg?branch=master)](https://app.travis-ci.com/jackocnr/intl-tel-input) <img src="https://img.shields.io/github/package-json/v/jackocnr/intl-tel-input.svg" alt="version"/> <img src="https://img.shields.io/npm/dm/intl-tel-input.svg"  alt="downloads"/>
 
-🎉 NEWS: we now have our own <a href="https://intl-tel-input.com/examples/react-component.html">React component</a>! Play with it on <a href="https://intl-tel-input.com/storybook/">Storybook</a>! 🎉  
+<img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/react.png" alt="React logo" width="16px" />  NEWS: we now have our own <a href="https://intl-tel-input.com/examples/react-component.html">React component</a>! Play with it on <a href="https://intl-tel-input.com/storybook/">Storybook</a>. 
 
-<img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/typescript.png" alt="Typescript logo" width="18px" /> ANNOUNCEMENT: since v21.0.6 we have our own Typescript type definitions (for both the pure JavaScript and the React plugin), so no need to use `@types/intl-tel-input` any more!
+<img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/typescript.png" alt="Typescript logo" width="16px" /> NEWS: we now have our own Typescript type definitions (for both [the JavaScript plugin](https://github.com/jackocnr/intl-tel-input/blob/master/build/js/intlTelInput.d.ts) and [the React component](https://github.com/jackocnr/intl-tel-input/blob/master/react/build/IntlTelInput.d.ts)), so no need to use `@types/intl-tel-input` any more!
 
-A JavaScript plugin for entering and validating international telephone numbers. It adds a (searchable) country dropdown to any input, detects the user's country, displays a relevant placeholder number, formats the number as you type, and provides comprehensive validation methods.
+🗣️ NEWS: we now provide [translation files](https://github.com/jackocnr/intl-tel-input/tree/master/build/js/i18n) for several common languages! [See them in action](https://intl-tel-input.com/examples/localise-countries.html).
+
+International Telephone Input is a JavaScript plugin for entering and validating international telephone numbers. It takes a regular input field, adds a searchable country dropdown, auto-detects the user's country, displays a relevant placeholder number, formats the number as you type, and provides comprehensive validation methods.
 
 <img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/vanilla-search.png" alt="Screenshot" width="238px" style="max-width: 100%" />
   
@@ -17,11 +19,12 @@ Use <a href="https://www.twilio.com/blog/international-telephone-input-twilio?ut
 ## Table of Contents
 
 - [Demo and Examples](#demo-and-examples)
+- [Mobile](#mobile)
 - [Features](#features)
 - [Browser Compatibility](#browser-compatibility)
 - [Getting Started](#getting-started-using-a-cdn)
 - [Recommended Usage](#recommended-usage)
-- [Options](#initialisation-options)
+- [Initialisation Options](#initialisation-options)
 - [Public Methods](#public-methods)
 - [Static Methods](#static-methods)
 - [Events](#events)
@@ -52,6 +55,7 @@ By default, on mobile devices we show a fullscreen popup instead of the inline d
 * Typescript type definitions provided
 * Easily customise styles by overriding the provided CSS variables
 * React component included
+* Translations for all country names (etc) provided in many different languages
 
 ## Browser Compatibility
 | Chrome |  Firefox  | Safari | Edge |
@@ -63,16 +67,16 @@ _Note: We have now dropped support for all versions of Internet Explorer because
 ## Getting Started (Using a CDN)
 1. Add the CSS
   ```html
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/intl-tel-input@21.1.3/build/css/intlTelInput.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/intl-tel-input@21.2.0/build/css/intlTelInput.css">
   ```
 
 2. Add the plugin script and initialise it on your input element
   ```html
-  <script src="https://cdn.jsdelivr.net/npm/intl-tel-input@21.1.3/build/js/intlTelInput.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/intl-tel-input@21.2.0/build/js/intlTelInput.min.js"></script>
   <script>
     const input = document.querySelector("#phone");
     window.intlTelInput(input, {
-      utilsScript: "https://cdn.jsdelivr.net/npm/intl-tel-input@21.1.3/build/js/utils.js",
+      utilsScript: "https://cdn.jsdelivr.net/npm/intl-tel-input@21.2.0/build/js/utils.js",
     });
   </script>
   ```
@@ -138,6 +142,8 @@ You can always get the full international number (including country code) using
 
 If you know the user's country, you can set it with `initialCountry` (e.g. `"us"` for the United States), and if you don't, we recommend setting `initialCountry` to `"auto"` (along with the `geoIpLookup` option) to determine the user's country based on their IP address.
 
+If you know the user's language, you can utilise the included translations to localise the country names (etc) - [see example](https://intl-tel-input.com/examples/localise-countries.html).
+
 ## Initialisation Options
 When you initialise the plugin, the first argument is the input element, and the second is an object containing any initialisation options you want, which are detailed below. Note: any options that take country codes should be [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.  
 
@@ -233,9 +239,16 @@ Which will generate the following (hidden) elements, which will be automatically
 
 **i18n**  
 Type: `Object` Default: `{}`  
-Allow localisation/customisation of country names and other plugin text. To localise a country name, the key should be the iso2 country code, and the value should be the localised country name. [See example](https://intl-tel-input.com/examples/localise-countries.html).
+Allow localisation/customisation of country names and other plugin text. There are two options: either import one of the [provided translation modules](https://github.com/jackocnr/intl-tel-input/tree/master/build/js/i18n) (see option 1 below), or define your own custom translations (see option 2 below). If defining your own, you will need to specify all country names (over 200 at last count - [see full list](https://github.com/jackocnr/intl-tel-input/blob/master/src/js/intl-tel-input/data.ts)) using their 2-character iso2 name, as well as the 7 interface keys listed below. [See example](https://intl-tel-input.com/examples/localise-countries.html).
 
 ```js
+// OPTION 1: import one of the provided translation modules
+import fr from "intl-tel-input/i18n/fr";
+
+intlTelInput(input, { i18n: fr });
+
+
+// OPTION 2: define your own custom translations
 intlTelInput(input, {
   i18n: {
     // Country names (see full list here: https://github.com/jackocnr/intl-tel-input/blob/master/src/js/data.js)