Merged Pull Request '#136 feature/country-translation->main: Add the country translation engines (ip-intelligence.translation)'

Add a new ip-intelligence.translation module with the two country
translation engines, ported from the .NET FiftyOne.IpIntelligence.Translation
package.

Engine 1 (CountryCodeTranslationEngine) reads the weighted ISO country
codes from the IP Intelligence engine and translates them to English
country names using countrycodes.en_GB.yml. Its source element data key
is configurable and defaults to "ip".

Engine 2 (CountriesTranslationEngine) translates those English names to
the browser language using the countries.<locale>.yml files, then builds
complete ordered lists: the weighted countries first (most probable by
weight, ties broken by translated name), followed by every remaining
country alphabetically. The code and name "All" lists are index aligned so
a demo can render a country dropdown with the most probable country first.

The translation YAML files are wired in at build time from the IP
Intelligence data submodule rather than shipped as new data.

Author: Jamesr51d

ip-intelligence.translation/pom.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>pipeline.ip-intelligence</artifactId>
+        <groupId>com.51degrees</groupId>
+        <version>4.4.21-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>ip-intelligence.translation</artifactId>
+    <name>51Degrees :: IP Intelligence :: Translation</name>
+    <description>Translation engines that turn the weighted ISO country codes
+        from 51Degrees IP Intelligence into localized, ordered country name and
+        code lists.</description>
+    <url>https://51degrees.com?utm_source=maven&amp;utm_medium=package&amp;utm_campaign=ip-intelligence-java&amp;utm_content=ip-intelligence.translation-pom.xml&amp;utm_term=url</url>
+
+    <dependencies>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>ip-intelligence.shared</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>pipeline.translation</artifactId>
+            <version>${pipeline.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>ip-intelligence.shared</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <!-- Used only by the integration test, which drives the real
+             on-premise engine end to end. Skipped when no data file is
+             present. -->
+        <dependency>
+            <groupId>${project.groupId}</groupId>
+            <artifactId>ip-intelligence.engine.on-premise</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- The country translation YAML files are not shipped as new data;
+                 they are wired in at build time from the IP Intelligence data
+                 submodule (mirroring the .NET project, which links the same
+                 files from ip-intelligence-data/Translations). -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <version>3.3.1</version>
+                <executions>
+                    <execution>
+                        <id>copy-translation-data</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.outputDirectory}/fiftyone/ipintelligence/translation</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>${project.basedir}/../ip-intelligence.engine.on-premise/src/main/cxx/ip-intelligence-cxx/ip-intelligence-data/Translations</directory>
+                                    <includes>
+                                        <include>countrycodes.en_GB.yml</include>
+                                    </includes>
+                                </resource>
+                                <resource>
+                                    <directory>${project.basedir}/../ip-intelligence.engine.on-premise/src/main/cxx/ip-intelligence-cxx/ip-intelligence-data/Translations/OSM</directory>
+                                    <includes>
+                                        <include>countries.*.yml</include>
+                                    </includes>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

ip-intelligence.translation/src/main/java/fiftyone/ipintelligence/translation/Constants.java

@@ -0,0 +1,51 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.ipintelligence.translation;
+
+/**
+ * Constants used by the country translation flow elements.
+ */
+public class Constants {
+
+    private Constants() {
+    }
+
+    /**
+     * Element data key used by
+     * {@link fiftyone.ipintelligence.translation.flowelements.CountryCodeTranslationEngine}.
+     */
+    public static final String COUNTRY_NAMES_KEY = "countrynames";
+
+    /**
+     * Element data key used by
+     * {@link fiftyone.ipintelligence.translation.flowelements.CountriesTranslationEngine}.
+     */
+    public static final String COUNTRY_NAMES_TRANSLATED_KEY =
+        "countrynamestranslated";
+
+    /**
+     * Element data key of the IP Intelligence engine, the source of the
+     * weighted country codes.
+     */
+    public static final String IP_INTELLIGENCE_KEY = "ip";
+}

ip-intelligence.translation/src/main/java/fiftyone/ipintelligence/translation/Resources.java

@@ -0,0 +1,119 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.ipintelligence.translation;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * Reads the translation YAML files that are wired in from the IP Intelligence
+ * data submodule and copied onto the classpath under this package by the build
+ * (see the module pom).
+ * <p>
+ * The set of country name locale files is known and stable, so the files are
+ * loaded by name rather than by scanning the classpath, which keeps loading
+ * reliable whether running from a directory or a packaged jar. A file that is
+ * not present is skipped.
+ */
+public class Resources {
+
+    /**
+     * The single country-code to English-name file. This is also the list of
+     * all known countries.
+     */
+    private static final String COUNTRY_CODE_FILE = "countrycodes.en_GB.yml";
+
+    /**
+     * The country English-name to localized-name files, one per shipped
+     * locale.
+     */
+    private static final String[] COUNTRY_FILES = new String[]{
+        "countries.de_DE.yml",
+        "countries.es_ES.yml",
+        "countries.fr_FR.yml",
+        "countries.it_IT.yml",
+        "countries.nl_NL.yml",
+        "countries.pl_PL.yml",
+        "countries.pt_PT.yml",
+        "countries.sv_SE.yml",
+        "countries.tr_TR.yml",
+        "countries.uk_UA.yml"
+    };
+
+    private Resources() {
+    }
+
+    /**
+     * Get the country name translation YAML files (English name to localized
+     * name).
+     * @return map of file contents keyed on file name
+     */
+    public static Map<String, String> getCountryResources() {
+        Map<String, String> result = new LinkedHashMap<>();
+        for (String name : COUNTRY_FILES) {
+            String content = read(name);
+            if (content != null) {
+                result.put(name, content);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * Get the country code translation YAML file (ISO code to English name).
+     * @return map of file contents keyed on file name
+     */
+    public static Map<String, String> getCountryCodeResources() {
+        Map<String, String> result = new LinkedHashMap<>();
+        String content = read(COUNTRY_CODE_FILE);
+        if (content != null) {
+            result.put(COUNTRY_CODE_FILE, content);
+        }
+        return result;
+    }
+
+    /**
+     * Read a resource from this package as a UTF-8 string, or null if it is
+     * not present.
+     */
+    private static String read(String name) {
+        try (InputStream stream = Resources.class.getResourceAsStream(name)) {
+            if (stream == null) {
+                return null;
+            }
+            ByteArrayOutputStream buffer = new ByteArrayOutputStream();
+            byte[] chunk = new byte[4096];
+            int read;
+            while ((read = stream.read(chunk)) != -1) {
+                buffer.write(chunk, 0, read);
+            }
+            return new String(buffer.toByteArray(), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            return null;
+        }
+    }
+}

ip-intelligence.translation/src/main/java/fiftyone/ipintelligence/translation/data/CountriesTranslationData.java

@@ -0,0 +1,101 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+package fiftyone.ipintelligence.translation.data;
+
+import fiftyone.pipeline.core.data.FlowData;
+import fiftyone.pipeline.core.data.IWeightedValue;
+import fiftyone.pipeline.engines.data.AspectPropertyValue;
+import fiftyone.pipeline.translation.data.TranslationData;
+import org.slf4j.Logger;
+
+import java.util.List;
+
+/**
+ * Concrete implementation of {@link ICountriesTranslationData}.
+ */
+public class CountriesTranslationData
+    extends TranslationData
+    implements ICountriesTranslationData {
+
+    /**
+     * Construct a new instance.
+     * @param logger used for logging
+     * @param flowData the {@link FlowData} the element data is added to
+     */
+    public CountriesTranslationData(Logger logger, FlowData flowData) {
+        super(logger, flowData);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<IWeightedValue<String>>>
+        getCountryNamesGeographicalTranslated() {
+        return getAs("CountryNamesGeographicalTranslated",
+            AspectPropertyValue.class, List.class, IWeightedValue.class,
+            String.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<IWeightedValue<String>>>
+        getCountryNamesPopulationTranslated() {
+        return getAs("CountryNamesPopulationTranslated",
+            AspectPropertyValue.class, List.class, IWeightedValue.class,
+            String.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<String>>
+        getCountryNamesGeographicalAllTranslated() {
+        return getAs("CountryNamesGeographicalAllTranslated",
+            AspectPropertyValue.class, List.class, String.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<String>>
+        getCountryNamesPopulationAllTranslated() {
+        return getAs("CountryNamesPopulationAllTranslated",
+            AspectPropertyValue.class, List.class, String.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<String>> getCountryCodesGeographicalAll() {
+        return getAs("CountryCodesGeographicalAll",
+            AspectPropertyValue.class, List.class, String.class);
+    }
+
+    @SuppressWarnings("unchecked")
+    @Override
+    public AspectPropertyValue<List<String>> getCountryCodesPopulationAll() {
+        return getAs("CountryCodesPopulationAll",
+            AspectPropertyValue.class, List.class, String.class);
+    }
+
+    @Override
+    public String getSortingCultureUsed() {
+        return getAs("SortingCultureUsed", String.class);
+    }
+}