How to add a new language support

Add new language support

Important notes

• In this entire process, you will add data manually only in buildSrc/ then a gradle task at the end will merge different translations + country information and write it in /countryPicker module automatically.
• You can find list of currently supported languages here.
• In this article, we will be adding support for Japanese (JA) language.

Let's get started

1. Checkout

• Checkout project and create a new translation branch from develop branch.

2. Update SupportedLanguage.kt

• Find SupportedLanguage.kt and add new entry for the language. For example, JAPANESE("JA"). "JA" is identifier of JAPANESE language. You can find identifier of languages here
• If the language contains region as well for example Chinese Traditional has language code ZH and region code TW, then the identifier for that would be ZH-TW.
• TODO-Add image

3. Auto-generate "placeholder" data

• To help developers add language support easily, there is a gradle task that will generate all the TODO placeholders that needs to be done to complete the language support.
• Run task named generatePlaceholderData. You can find it in AndroidCountyPicker > Tasks > automation.
• Based on your added language, it will create translation file, figure out missing translations add placeholders that starts with "CP_TODO"

3. Check if IP2LOCATION translations exists for your language

• This library uses official country info and translations from IP2LOCATION
• Check if IP2LOCATION-COUNTRY-MULTILINGUAL.CSV file contains translations for the language you are looking for.
  • 
  • If it exist, it means these translations will be automatically added as string resources when you will gradle task at the end. You do not need to write these translations manually.
  • If it does not exist, you will need to provide those in the next step.
  • If any of these translations are incorrect/incomplete, you can correct those translations in next step.
  • DO NOT CORRECT / UPDATE this file. It will be overridden when new data is available from IP2LOCATION.

4. Add translations for additional countries

• IP2Location does not have data of some countries (additional countries) that this library supports. You can find those countries in ADDITIONAL-COUNTRY-INFORMATION.CSV file.
• Translations of these countries are added in ADDITIONAL-COUNTRY-MULTILINGUAL.CSV.
• Open this file and add translation for those other countries. For example there is only one additional country at the time of writing this, "Kosovo", add Japanese translation for that country.
• If you want to make some correction for translation in previous step IP2LOCATION-COUNTRY-MULTILINGUAL.CSV, then add them here too. These translation will override that incorrect value when string resources are generated.
• If IP2LOCATION-COUNTRY-MULTILINGUAL.CSV did not have translation for your language in last step, you will need to add translation for all countries manually here.
• 

5. Add messages translations

• Library uses some messages like
  • "No matching result found" when search filter has no result for given term
  • "Search…" hint text for search box
  • "Select a country" - title of the dialog
  • "County" - A placeholder text for country picker view when no country is selected
  • "Clear Selection" - Text of button to clear existing selection
• Open MultilingualCPMessages.kt to add these translations
  • 

6. Check updated files

• At this point, you should have updated only /buildSrc module and only these 3 files (in yellow)
• 

7. Generate string resources

• Now find and run gradle task named generateCPAndroidResource in gradle task window. This task will merge and generate resources from the data in /buildSrc.
  • 
• If there is some missing translation, this will fail with error. For example, if we had missed to add Kosovo translation, it will say like
  • 
• If there is no issue with the provided data, this task will generate resources successfully.

8. Check generated data

• Since we just added new language support, it will create two new language specific (/values-ja) translation files in countryPicker library module. One of those is for country name translations and other for messages translation. Just make sure they are generated correctly.
• 

9. Update CHANGELOG.md

• Add change log entry with your name and GitHub handle.
• - Japanese language support by Harsh Bhakta (@hbb20)
• 

10. Create PR. Thank you.

• Finally, create a PR. It will look something like this.
• In PR, let us know if release of this is time sensitive for you.

You are all set. Thank you for your contribution. 🙏🏼