Better multi-country support in Contacts | Winfred van Kuijk

Better multi-country support in Contacts

By • Published: January 4, 2010 • Last updated: June 4, 2023 • Filed in: Software

Here is a free plug-in that I have written for Apple’s Contacts (Address Book) that provides better multi-country support:

  • country names: you no longer have many variations for country names (so: all “United States”, instead of many variations like “USA”, “US”, “United States of America”);
  • country address formats: it tells Contacts to use the formatting that belongs to that country (e.g. my default format is for the Netherlands, which normally means for US addresses that state is missing and zip and city are switched).

Before (left): non-standard country name and incorrect format (state is missing, zip and city are switched)
After (right): standard country name and correct format

Quite useful for those that have contacts in multiple countries. You can specify in the script what countries to check and what your preferred country names are. Missing/unknown countries are added as a group in Contacts.

Simply download and run, or install as plug-in in /Library/Address Book Plug-Ins ~/Library/Application scripts/ (location appears to have changed in 10.9.2.

September 2014: v1.9 introduces progress meter (available in Yosemite), user request added (only process contacts in defined group), bug fixes.

Standard country names

Before I had the script, I had many variations of country names (“United States”, “United States of America”, “USA”, “US”, etc.). For filtering and searching it would be nice to have a standard country name. The script looks for -defined by you- country name aliases and replaces them by the -defined by you- preferred name.

Related, request for Apple: please add filtering for country. I can filter (smart group) based on city, state or zip… but not country. In the mean time I use the generic address filter when I want to create a smart group.

Country address formats

It took me a while to discover the -built in- support for address formats. While in Edit mode, you can click on the address label (e.g. work/home) and then select the Change Address Format. What this does is setting the Country Code field, which is the iso code for that country. Not only is this setting difficult to find, it is a pain to do it if you have many international cards. Plus: if the country is already known, why would you have to do this at all?

This is where the script helps. When you run it, it will look for the regular country field and if it is one of the recognized names then it will set the country code.

Here are a couple of examples of the different country formats (click to enlarge):

Default country format

In the settings you can define your default country format:

Download the script

Download “AppleScript - fix country names and formats in Contacts”

contacts country names and – 85.12 KB
before updating, first copy settings + the country table.

Revision history:
v1.0, 2010/01/03, initial release
v1.1, 2010/01/04, added result display options, added ability to run as Address Book plugin, Growl support
v1.2, 2010/01/10, added support for all known iso countries, write results to log file for easy copy/paste
v1.2.1, 2010/01/11, small Growl fix for non-Growl users
v1.2.2, 2010/01/12, leave iso code empty in lookup list to overwrite Apple’s format + check small countries if not in large country list
v1.3, 2010/01/12, added support for optional checking of latest version of plug-in
v1.4, 2010/01/15, added support for groups: adds missing/unknown country entries, extra check for problematic cards
v1.5, 2010/02/06, using “iPhone” country list instead of official ISO list, changed default values of some parameters
v1.5.1, 2011/07/28, small fixes, Lion compatibility, changed default values of some parameters
v1.5.2, 2011/08/20, small fixes, growl fix, user request: made preferred country case sensitive
v1.6, 2013/03/31, renamed script, fixed country code for Japan and Czech Republic, speed improvement for searching countries,
fix for read-only accounts (e.g. Facebook), removed Growl to improve Mac OSX compatibility, use optional notification center script, quick install in Terminal: sudo gem install terminal-notifier
v1.7, 2013/10/26, compatibility with Mavericks, use native notifications (10.9 or higher), improved detection of read-only accounts (Facebook etc.)
v1.8, 2014/01/13, user suggestion: create summary of countries per country code
v 1.9, 2014/09/01, Yosemite progress support, user suggestion: only check contacts in a specific group (property check_only_contacts_in_group), bug fixes

How to install & run the script

After downloading the .zip file, double click to unzip. You will now have the Applescript script.
There are two options to run the script:

  • plug-in for Contacts (preferred): install the script in [user home]/Library/Address Book Plug-Ins [user home]/Library/Application scripts/ (per user) or /Library/Address Book Plug-Ins /Library/Application scripts/ (all users). Note: the location has changed since 10.9.2. To use: select an address label (work/home/etc.) and click on “Check all country names and codes”.
  • standalone: save the script anywhere and double-click to open in Apple’s Script Editor. Optionally you can uncomment the log lines to get a detailed log of the actions.

For both (optional): open the script in AppleScript Editor and customize the sections between #### … #### (see customize section). Restart Contacts if you make changes to the settings or table. Run the script as often as you like.


By default (as of version 1.4), you will get feedback in Contacts itself. Two groups will automatically be created and filled with people:

  • that have an address in an unknown country (note that “unknown” can also mean: not in your country table);
  • that have an address, but where the country field is empty.

Note that this is an *add-only* action (and not a “smart group”), it is up to you to clean/remove the groups when you have modified the records.

If you want, you can get a summary at the end (by setting the optional parameter show_results). A summary will be placed on your Desktop and opened in TextEdit.

The unknown country section is ready for copy&paste to the script. Go through the list, modify it the way you like and make sure no “??” iso codes remain.
The missing countries section is FYI, you can update those addresses if you want to. It is the same names that appear in the “without country group”.


The performance depends on the size of your Contacts database and how clean the data is.
E.g. for me it took 81 seconds the first time (656 people checked, 81 country names updated, 480 country formats updated), now it takes about 4 seconds.

Test vcards

If you want to test the script before you let it check all your address book cards, enable the setting in the script and create entries in Address Book with last name “testing”. Instead of creating them yourself, you can also download the test cards I have used.

[Download not found]

After testing, you can disable the setting again and delete the cards from your Address Book.

Customize the script

It is up to you to tell the script what country names to look out for.
The structure: iso code, list of preferred name and -if you want- aliases for that country. The bottom of the script has a list of all of the iso country codes and names, in the list at the top you tell it what you want it to look like. Different language, add alternative names/languages, etc. Is the standard entry in the iso list ok with you? Then there is no need to add it to the top list (although, if you do: it will speed up the script).

Note: only use the iso codes from the bottom list of the script, these are the ones that Apple recognizes. Any unknown iso codes will result in Contacts hiding that address (even though the iso code is legal, e.g. “AN” for “Netherlands Antilles”).

This is what the list could look like:

copy {"nl", {"Netherlands", "Nederland", "the Netherlands", "NL"}} to end of clist
copy {"be", {"Belgium", "België", "Belgique"}} to end of clist -- use the English name
copy {"de", {"Deutschland", "Germany"}} to end of clist -- use the German name
copy {"gb", {"United Kingdom", "UK"}} to end of clist
copy {"us", {"United States", "USA", "US", "United States of America"}} to end of clist
copy {"fr", {"France"}} to end of clist -- example of country with no aliases
copy {"ve", {"Venezuela"}} to end of clist -- example of overwriting name from iso list
copy {"", {"Chile"}} to end of clist -- use "default country" format instead of Apple's format
--copy {"??", {"Luxembourg"}} to end of clist -- incorrect, iso code is missing
--copy {"an", {"Netherlands Antilles"}} to end of clist -- incorrect, Apple does not know this iso code
-- add as many lines as you like...

In the script you can set various parameters, the main ones:

  • add_to_groups: (default: true) create groups for entries with missing/unknown countries; is *add-only*, so clean up manually
  • show_results: (default: true) give feedback afterwards -see below-, shows contacts where country field is empty, and countries that are not in your table.

Your own language

Here is a quick example to show how you can set the language.

The first example will look for “Germany” in German and French and use the English version of the country name.

copy {"de", {"Germany", "Deutschland", "Allemagne"}} to end of clist

You prefer the German version? Simply make that the first name in the list entry. It will look for all entries “Germany” and “Allemagne” in your Contacts and replace them with “Deutschland”.

copy {"de", {"Deutschland", "Germany", "Allemagne"}} to end of clis

You don’t like the format that Apple picks for your iso code? Just pick another iso code or leave the field empty (it will then use your default country format).

68 Responses to “Better multi-country support in Contacts”

  1. Michael Cook says:

    Thank you so much for this! I couldn’t get it to work as a plugin in Mountain Lion, but running it with the Apple Script Editor produced the desired result.

    • winfred says:

      Thanks Michael. Do you have details about trying to get it to work in Mountain Lion? It is working for me, so interested in what you did so I can investigate. Feel free to use the contact form to send details.

  2. Gabrielle says:

    This plugin worked for me! Easy to install and fast. Thank you, thank you….

  3. Kit Mosden says:

    I don’t know if you can help or not but I am pulling my hair out over this. Address Book keeps duplicating an address and adding a different country. So if I have 123 Main St Anywhere CA USA it adds 123 Main St Anywhere CA CANADA. It seems to happen somewhere in syncing but I can’t figure out where/how. I have corrected everything in Address Book and when syncing to my iPad Replaced all data on the iPad. It’s fine for awhile and then suddenly Address Book changes my data by adding the wrong Country again. I’ve cleaned this up 3 or 4 times and am really sick of it.
    Any ideas or suggestions?Kit


  4. johann beda says:

    I get a “Download path is invalid!” error when trying the download link at from the download button link:

    or from the “view the script as text” link:

  5. ETC says:

    Hi, Winfred. I see you’ve got 1.5.2 out. Thank you. I appreciate all your work on this script. I think it’s a great tool.

    I just tried it and got this error message when I tried to edit it: “Unable to read the file because the script is not editable (it was saved as run-only).”

    I also noticed that the version history on this page does not have 1.5.2 on it.

    • winfred says:

      Hi Eric,
      Run-only: this is an unfortunate side-effect of Applescript. You can execute the plug-in with or without Growl installed. If you want to edit the script then you *need* to have Growl installed. I am continuing to look into a real fix.
      Version history: well spotted, updated.

      • ETC says:

        I tried to like Growl, but couldn’t. Maybe I should try again.

        I think everyone has to edit your script, right, in order to copy of the specific settings they need? So if it’s uneditable without Growl, it’s unusable without Growl. Or did I misunderstand?

        • winfred says:

          That’s indeed the correct summary.
          If a script refers to an application that is not installed, then Applescript opens the script as run-only. Hopefully this can be fixed in the future.
          Keep in mind: you only have to *install* Growl, it does not have to *run* in the background, you can still choose to disable Growl in the System Preferences.

  6. ETC says:

    Every time I edit the script, before the AppleScript Editor shows the script I get a notice two times saying, “Where is the” After I click “Cancel” it eventually goes away and the script loads for editing. I used to have Growl on my machine, but have uninstalled it. In your script I have set the “use_growl” option to “false”. Thank you for the umpteenth time, Winfred!

  7. ETC says:

    Strangely, enough, when I have this line in the Script

    copy {“gb”, {“UNITED KINGDOM”, “UK”, “U.K.”, “U. K.”, “GB”, “United Kingdom”}} to end of clist —

    and the country field has “United Kingdom” in it, the script does not change it to “UNITED KINGDOM”. Is there something I am doing wrong?

  8. ETC says:

    I wonder if you could help (or even someone else could) with addresses in the United Kingdom. Apple’s Address book gives only 5 fields to fill in: Street, City, County, Postcode, Country. “Country”, however, is reserved for “United Kingdom”, though the actual country (in the mind of a native, perhaps?) may be Wales, England, Scotland, or Northern Ireland (technically, the “Province of Ulster”, I guess). So where should one put the “England”, or “Scotland” or “Wales” or “N. Ireland”? I guess in the county field is the only option I can imagine, e.g., “Co. Antrim, N. Ireland”. Is that right? It seems to me in looking at addresses on websites, that they usually list the county on one line above the “N. Ireland” or “England” or whatever.

  9. ETC says:

    Thanks Winfred,
    I wonder how others cope without your script! I was able to download the 1.5.1 script from the radio button “Download”, however, when I clicked on “To view the script as text: AppleScript – text – fix country names and formats in Address Book”, I still got 1.5. Probably a broken link there, too.

  10. ETC says:

    Hi, Winfred,

    Just wondering why the 1.5.1 script does not have its own “1.5.1” in the version history, and why “property current_version : “1.5”” is not “1.5.1”. Won’t that mean it’ll still tell me to update, even though I have the most recent version?

    Also, can you share what changes had to be made to comply with Lion (OS 10.7)?

    Thank you very much for this script!

    • winfred says:

      Hi Eric, thanks for reporting. It seems the upload of the 1.5.1 version was not successful. Should be working now. Lion compatibility: I changed the way the report log is opened in TextEditor. Any other issues (or requests): let me know.

  11. ETC says:

    OK, I’ve finally gotten over my own problems, as least most of them!

    These questions are still relevant for me (in case you’ve not gone to sleep reading my posts):

    Q1: what happens if I set “treat_iso_list_as_unknown” to false AND also have a country listed in the list at the top and use a different preferred spelling in the list at the top?

    Q2: In the case of your testing vCard (“country not in alias list” “testing”), used with Spain, am I correct that your script is supposed to do nothing to such addresses in such cases?

    Q3: If my assumption in Q2 is correct, would it be a possible enhancement to have your script make a list of all such addresses and in a group called, say, “• without country in alias list”. I have over 400 addresses in my Address Book, and I really don’t even know without scanning them all, which countries I should add to the list at the top.

    • winfred says:

      Wow, you took a close look at the plugin, I’m impressed. 🙂
      Q1: putting countries in the top list will override any entries in the iso (=bottom) list. The value for “treat_iso_list_as_unknown” should have no effect there.
      Q2: for the Spain test card, it will indeed do nothing. The card’s country name is “España”, and the bottom iso list only mentions “Spain”. So: it is treated as an “unknown country”.
      Q3: with the parameter add_to_group set to yes (=default), you should get exactly that, e.g. the Spain test card shows up in the “• unknown country” group, because the “España” country is not in the list.
      The show_results parameter (default: yes) will put these “unknown country” records in a text file (which is placed on the Desktop and opened in TextEdit)
      By editing this file, you can a) specify which country format to use for such “unknown country”, and/or use a different preferred country name (e.g. “España” instead of “Spain”)
      Just edit this file, replace “??” with official iso codes (only use iso codes from the bottom list!), and optionally: add a new preferred country name and then add these entries to the top list.

      Hope this helps, do not hesitate to send mail if you have other questions. More than happy to assist.

      • ETC says:

        Thank you very, very much! I got it all working wonderfully, updated all my addresses, and now have it set so as I enter any one address, I can use your script to change the layout of the address to the proper one without selecting from the time-consuming drop down formats list. And yes, I finally did figure out that the “• unknown country” group was giving me exactly the info I needed (i.e. which addresses had no country entered in them, or the countries were not in the top list. I really appreciate this plug-in!

  12. ETC says:

    Well, if I keep this up, you’ll get really bored with me! Sorry. I see now that Address Book must be restarted (I just missed that in your documentation). I restarted, and it tried to run, but I was limiting changes to one entry (see below) and it was on of your testing vCards for Spain, but I didn’t have Spain in my list at the top.

    Q: With the “propery plugin_only-selected: true” setting, am I right that I do NOT have a choice to update all records, but only the current address? I thought it would give me an option: “Do you want to update only this one or all? That was my impression from the text “only update selected person or run for every person?”

  13. ETC says:

    I now see part of the problem: no quotation marks in my Lithuania line. But that doesn’t solve the other problems.

    I corrected the Lithuania line to this:

    copy {“lt”, {“LIETUVA (LITHUANIA)”, “LITHUANIA”, “Lithuania”, “LITHUANIA (LIETUVA)”, “Lietuva”, “LIETUVA (LITHUANIA)”, “LITHUANIA (Lietuva)”}} to end of clist —

    When I run the script, it changes no addresses.

    I changed this line to “true”, but saw no difference. Why?

    property plugin_only_selected : true — when using as plug-in: only update selected person or run for every person?

    Do I need to exit the AppleScript Editor or restart Address Book?


  14. ETC says:

    Hi, Winfred,

    Nice script!

    Here’s what I currently have:

    copy {“us”, {“USA”, “United States”, “US”, “United States of America”, “Estados Unidos”}} to end of clist
    copy {“nl”, {“Netherlands”, “Nederland”, “the Netherlands”, “NL”}} to end of clist
    copy {“be”, {“Belgium”, “België”, “Belgique”}} to end of clist — I like to use the English name for this country
    copy {“de”, {“Germany”, “Deutschland”}} to end of clist — using the English name
    copy {“gb”, {“United Kingdom”, “UK”}} to end of clist — note: Address Book uses “gb” as country code, not “uk”
    copy {“fr”, {“France”}} to end of clist — optional: direct copy from iso list, only advantage: faster search
    copy {“lt”, {“LIETUVA (LITHUANIA)”, LITHUANIA, LITHUANIA, Lietuva, Lietuva, Lietuva(LITHUANIA), LITHUANIA(Lietuva)}} to end of clist —

    Q1: I want Lithuanian addresses in Address Book to have this country: LIETUVA (LITHUANIA). Many are already entered that way in my Address Book database. I’m having trouble getting an “alias” inputted correctly in your script.

    I typed in this line:

    copy {“lt”, {“LIETUVA (LITHUANIA)”, LITHUANIA, LITHUANIA, Lietuva, Lietuva, Lietuva (LITHUANIA), LITHUANIA (Lietuva)}} to end of clist –

    AppleScript Editor took out the space I had before the opening parentheses and made the text green, but the parentheses black. Do I somehow need to mark the parentheses so they are “escaped” or treated a characters? If so, how do I do it?

    Q2: what happens if I set “treat_iso_list_as_unknown” to false AND also have a country listed in the list at the top and use a different preferred spelling in the list at the top?

    Q3: I want the US addresses to have “USA” listed, not “United States”. That’s why I changed the “us” line. But the script put in “United States” anyway. What did I do wrong?

    Thank you!

  15. Simon from Switzerland says:

    Found your script for “Address Book” and it works great. Thanks for sharing. I’m a fan!

Leave a Reply

« | Home | »