Unlocking a world of country information
Effortless integration of multilingual country lists into your TYPO3 project
Since the early days of TYPO3, creating a simple list of countries has been an ever-present use case — most commonly for designing contact forms, or extension authors building out a user registration process.
Including a list of countries in any kind of frontend form required an integration to TYPO3’s own form framework (covered via the extension Form Country Select), or an integration to the powermail extension (Powermail Country Viewhelper).
Before TYPO3 v12, a useful extension called “Static Info Tables” was available. This extension provides a statically available database table containing a list of all countries and other static information, such as a list of all languages or currencies. This extension has been around for about 20 years and has always been compatible with the latest version of TYPO3.
Unfortunately, the extension has a few downsides:
- Information was only available with the English name (for example, “Switzerland” and not “Schweiz” as for the Suisse users)
- The data was stored in a database, so a database query was needed every time a user selected a country from a form.
The first obstacle has been overcome with additions to the extension, usually with a suffix such as “static_info_tables_da” for the Danish translations of this list. However, those additions were not always as up-to-date as the main extension.
The second point was related to the conceptual functionality of the system and was based on historical reasons. The list of installed extension data was not subject to any changes, so there was no need to keep the database busy with such information. After all, there are more elegant ways to retrieve this data.
TYPO3 v12 addressed all of these issues by including this functionality in Core, using the Country API to retrieve a full list of up-to-date countries.
To learn more about the latest version of TYPO3 and how to upgrade your installation, contact us.
How TYPO3 retrieves the list of countries
TYPO3 Core contributors have made an effort to analyze various existing open-source solutions on where to find the “official list” of countries. It is not such a simple task because country names themselves aren't static. For example, the country of Turkey changed its official English name to Türkiye in 2022.
The widely known Debian Linux open-source project provides an up-to-date list of all countries, their full names, and their official English names as defined by the United Nations and the ISO standard ISO 31-664. Fortunately, this list is also available in JSON format and provided by a PHP wrapper as a Composer package called “sokil/php-isocodes-db-i18n”. In addition, this package ships not just the English version but also all names and official names in various languages — including all the officially supported languages (50+) of TYPO3 Core.
Instead of shipping this JSON format package for every project, TYPO3 only requires this package in the mono-repository, and transforms the JSON file into a complete PHP class — which is thus optimized by PHP’s runtime and can be cached natively by PHP. All translations are then added as XLF files, so TYPO3’s regular behavior for translating strings is taken into account. Functionality, such as overriding XLF files (just like any other XLF file), can be applied, and the correct translation is connected to the selected Site Language in TYPO3’s frontend or the backend users’ selected language in TYPO3's backend.
A continuous integration job checks for updates of this package regularly, so TYPO3 Core always ships with the full list of all countries as defined by the United Nations.
How to use the Country API in extensions
For extension authors, the Country API is as simple as it can get.
There is a single entry point:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$provider = new \TYPO3\CMS\Core\Country\CountryProvider();
// get a list of all countries
$allCountries = $provider->getAll();
// get information about a specific country
$switzerland = $provider->getByIsoCode('CH');
$switzerland->getName(); // Switzerland
$switzerland->getOfficialName(); // Swiss Confederation
// And use the LanguageService to use a localized version
$languageService = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Localization\LanguageServiceFactory::class)->create('de-CH');
$languageService->sL($switzerland->getLocalizedNameLabel()); // Schweiz
There are ways to filter the full list down to only a specific selection, which is handy for creating your country dropdowns, but we will get to that differently.
But note: Make sure the language and country codes are copied correctly when adding them to TYPO3.
A native Fluid ViewHelper
Most use cases are on a Fluid-level in Extbase extensions. A new ViewHelper <f:form.countrySelect> has been added:
1
2
3
4
5
6
7
<f:form.countrySelect
name="country"
value="CH"
sortByOptionLabel="true"
prioritizedCountries="{0: 'DE', 1: 'AT', 2: 'CH'}"
excludeCountries="{0: 'IR'}"
/>
This ViewHelper uses the Country API and provides a <select> HTML element with a list of all countries but shows Germany, Austria, and Switzerland on the very top, with Switzerland being preselected. A list of countries can also be removed from the selection. The label within the select options for each country is automatically localized in the currently used site language.
Form Framework: Country Select
The Form Framework ships with a new Country Select element, which editors can now use to create a dropdown with the same options as the ViewHelper.
TYPO3: An easier way for recurring challenges
Instead of dealing with an infinite amount of additional extensions for a simple selection of countries, TYPO3 offers this functionality out-of-the-box, in a standardized and robust way, without any compromises to performance — by just using PHP and the XLF translation files.
Of course, some existing extensions for country lists, such as “static_info_tables,” are not rendered obsolete because they offer flexibility and lists of static data that cater to some use cases. But TYPO3 now makes life a bit easier — for new projects or when estimating an upgrade to avoid many third-party extensions.
Want to know more about the latest TYPO3 version? Need help while upgrading? Contact us!
Additional resources:
- Changelog v12.2 Feature #99618 - List of countries in the world and their localized names
- Changelog v12.3 Feature #99735 - New Country Select form element