Country acronym to text translator function in APEX

Sometimes we have acronyms for Countries or States in our org’s fields. Which might be just fine for our users to handle on a daily basis. However, using acronyms in, for instance, reports for our clients, is not really fancy.

In this article we are going to check how to create a public function that helps us translating “ES” into “Spain”, “España” o “Spagne” wherever we need it.

Long story short, this is what we will do:

1. Create a custom setting in Salesforce

2. Populate the custom setting with ISO values

3. Create a method to obtain the “translation”

4. Create a method to get the phone code (bonus)

Create a custom setting in Salesforce

You can do this via APEX, but this is quite fast through UI.

1. Go to: Setup > Schema Settings
2. Activate the option “Manage List Custom Settings Type”. We need to activate this in order to create a Custom Setting “List”.

3. Go to: Setup > Custom Settings and Hit New.

4. Create the following fields. The names could be any you wish, but just consider they should self-explainatory.

1. Country Name Spanish – Text (100)
2. Country Name French – Text (100)
3. Country Name English – Text (100)
4. ISO2 – Text (5)
5. ISO3 – Text (5)
6. Telephone Code – Text(5)

5. One note about this, List type Custom Settings have a Name filed that must be populated. You don’t need to create this field. SF will automatically create it.

2. Populate with ISO Values

To download a complete CSV or JSON data for ISO Country Codes, you can go to this Cool Github Repository and click on “Conversor del CSV a otros formatos” (don’t worry, this is the only thing you’ll find in Spanish).

1. Chances are that you are developing in Sandbox so, you really do not need to populate all these values in the sandbox environment right away. Create a few for testing sake.
2. When you deploy to production, you will definitely have to populate the Custom Settings records. Which you can do via:
   1. Spoon / Kettle (recommended). You can check on how to use this great software to import, transform and export data to Salesforce (among others) in this article from Carlos Meseguer.
   2. Importing a JSON via APEX Anonymus Window (not recommended). For this alternative you should should use JSON format for the incoming data. Which implies:
      1. Upload JSON as a static resource
      2. In your APEX Window, create an inner class to use as a type for deserializing JSON.
      3. Once deserialized, then create the records for the custom setting with DML operations just as usual.
   3. Data Import Wizard. All in all, Custom Settings are actually Salesforce Objects and you can interact with them as such. You should be able to locate your new custom setting as an object in the Custom objects list. See pic below:

Warning! : No matter the via you choose, you need to add a column called “Name” and build it with the pattern “XX-ISO”, where ‘XX’ is the acronym. This is how your data should look like before uploading.

Create a method to obtain the “translation”

Once created our Custom Setting and populated, the rest is pretty straight forward. Just bear in mind that Custom Settings have their own methods, which we will be using.

public with sharing class getCountryDetails {

//Out method will receive the country acronym and the language of the country name we want to receive the result. 

    public static String getCountryNamePerLanguage(String acronym, String languageAcronym){

//Wrap in a try catch ir order to avoid null pointer exceptions and catch unmatched values.

    try{

//Build the "Name" field in order to get tha dataSet. Remember that our custom settings' name follows the pattern "XX-ISO". 

        sonn_countryISO__c dataSetForCountry= sonn_countryISO__c.getValues(acronym+'-ISO');
      
// Handle return values according to language
       switch on languageAcronym {
           when 'ES' {
               return dataSetForCountry.sonn_nombre__c;
           }
           when 'EN' {
               return dataSetForCountry.sonn_name__c;
           }
           when 'FR' {
               return dataSetForCountry.sonn_nom__c; 
           }
           when else {
               return dataSetForCountry.sonn_name__c;
           }
       }
    } catch (Exception error){

// You can also make it return null. But remember to control the behaviour after when you call it. In this case it just returns the acronym.

        return acronym;
    }
     
  }

}

Create a method to get the phone code (bonus)

Since we already have this info, why not? This is the same, but event simpler:

   public static String getPhoneCode (String acronym){
        try{
                sonn_countryISO__c dataSetForCountry= sonn_countryISO__c.getValues(acronym+'-ISO');
    return dataSetForCountry.phone_code__c;
        } catch (Exception error) {
            return ''; 
        }

    }

And just in case, do not forget about your tests! Here I leave you a test for both methods, including the Test Data.

@isTest
public with sharing class getCountryDetailsTest {
    @isTest
    public static void getCountryEN(){
        String acronym = 'AS';

        String countryName = getCountryDetails.getCountryNamePerLanguage(acronym, 'EN');

        System.AssertEquals('Saint Barthélemy', countryName, 'check country');
    }
    @isTest
        public static void getCountryES(){
        String acronym = 'AS';

        String countryName = getCountryDetails.getCountryNamePerLanguage(acronym, 'ES');

        System.AssertEquals('San Bartolomé', countryName, 'check country');
    }
    @isTest
        public static void getCountryFR(){
        String acronym = 'AS';

        String countryName = getCountryDetails.getCountryNamePerLanguage(acronym, 'FR');

        System.AssertEquals('Saint-Barthélemy', countryName, 'check country');
    }
    @isTest
    public static void getOtherLang(){
        String acronym = 'EH';

        String countryName = getCountryDetails.getCountryNamePerLanguage(acronym, 'NL');

        System.AssertEquals('Western Sahara', countryName, 'check country');
    }
    @isTest
    public static void getPhoneCodeTest(){
        String acronym = 'AS';
        String code = getCountryDetails.getPhoneCode(acronym);
        System.AssertEquals('590', code, 'check phone');
    }

// At this point you could also add a failing test, to check the correct behaviour if the input is incorrect or null.

@TestSetup
static void makeData(){
List<sonn_countryISO__c> countries = new List<sonn_countryISO__c>();

sonn_countryISO__c newCT2 = new  sonn_countryISO__c();
newCT2.Name = 'EH-ISO';
newCT2.sonn_nombre__c =  'Sahara Occidental';
newCT2.sonn_name__c =  'Western Sahara';
newCT2.sonn_nom__c=  'Sahara Occidental';
newCT2.iso2__c =  'EH';
newCT2.iso3__c =   'ESH';
newCT2.phone_code__c =  '';
countries.add(newCT2);

sonn_countryISO__c newCT1 = new  sonn_countryISO__c();
newCT1.Name ='AS-ISO';
newCT1.sonn_nombre__c =  'San Bartolomé';
newCT1.sonn_name__c =  'Saint Barthélemy';
newCT1.sonn_nom__c=  'Saint-Barthélemy';
newCT1.iso2__c =  'BL';
newCT1.iso3__c =   'BLM';
newCT1.phone_code__c =  '590';
countries.add(newCT1);

insert countries; 
}

}

Peace and Code!

Nadine