Trying MF 2.0 Final Candidate

Contents

  1. C++ Linux & macOS
  2. C++ Windows with Visual Studio
    1. From Visual Studio with minimal work
    2. From command line
    3. From Visual Studio (UI)
  3. Java
    1. What you need
    2. Instructions

C++ Linux & macOS

  1. Prepare a sandbox folder

     export ICU_SANDBOX=~/hello_icu_mf2
 mkdir $ICU_SANDBOX
 cd $ICU_SANDBOX

  2. Build ICU4C (you only need to do this once)

     git clone https://github.com/unicode-org/icu.git
 pushd icu/icu4c/source

 # Run this and choose the platform and toolchain you prefer
 ./runConfigureICU --help

 # if macOS
 ./runConfigureICU macOS/gcc
 # else if Linux  (gcc is just an example, there are 5 Linux options)
 ./runConfigureICU Linux/gcc
 # end

 export DESTDIR=$ICU_SANDBOX/icu_release
 make -j8 releaseDist
 popd

  3. Create a minimal C++ file here (we are in the $ICU_SANDBOX folder) called hello_mf2.cpp (click to view and/or download). The contents are reproduced below.

     // hello_mf2.cpp
 #include <iostream>

 #include "unicode/utypes.h"
 #include "unicode/calendar.h"
 #include "unicode/errorcode.h"
 #include "unicode/locid.h"
 #include "unicode/messageformat2.h"

 using namespace icu;

 int main() {
     ErrorCode errorCode;
     UParseError parseError;
 
     icu::Calendar* cal(Calendar::createInstance(errorCode));
     cal->set(2025, Calendar::JANUARY, 28);
     UDate date = cal->getTime(errorCode);
 
     message2::MessageFormatter::Builder builder(errorCode);
     message2::MessageFormatter mf = builder
             .setPattern("Hello {$user}, today is {$now :date style=long}!", parseError, errorCode)
             .setLocale(Locale("en_US"))
             .build(errorCode);
 
     std::map<UnicodeString, message2::Formattable> argsBuilder;
     argsBuilder["user"] = message2::Formattable("John");
     argsBuilder["now"] = message2::Formattable::forDate(date);
     message2::MessageArguments arguments(argsBuilder, errorCode);
 
     icu::UnicodeString result = mf.formatToString(arguments, errorCode);
     std::string strResult;
     result.toUTF8String(strResult);
     std::cout << strResult << std::endl;
 }

  4. Build your application and run it

     g++ hello_mf2.cpp -I$DESTDIR/usr/local/include -std=c++17 -L$DESTDIR/usr/local/lib -licuuc -licudata -licui18n

 # if macOS
 DYLD_LIBRARY_PATH=$DESTDIR/usr/local/lib ./a.out
 # else if Linux
 LD_LIBRARY_PATH=$DESTDIR/usr/local/lib ./a.out
 # end

    This will output

     Hello John, today is January 28, 2025!

C++ Windows with Visual Studio

From Visual Studio with minimal work

These instructions will use a release version of ICU4C (tested with 76.1) and a “Hello ICU world” project already created. They provide minimal effort that only requires downloading and opening in Visual Studio before using.

:point_right: Note: the MessageFormat 2 implementation in a previously release version may be behind the spec in the first few releases of ICU after the MF2.0 spec was declared 1.0 in CLDR 46.1, which occurred between ICU 76 and ICU 77. The difference between latest MF2.0 and the spec version supported in ICU may be minimal.

  1. Download the Visual Studio artifacts from the official release of ICU 76.1:

  2. Download the “Hello ICU / MF2 World” project HelloMF2.zip.

  3. Unzip the files you just downloaded and merge the content of the two ICU folders. The “hello world” project to be a sibling to the icu folder.

  4. The folder tree structure should look like this

     someFolderOfYourChoice\
   +- HelloMF2\
   | \- HelloMF2\
   \- icu\
     \- icu4c\
       +- bin\
       +- bin64\
       +- include\
       | \- unicode\
       +- lib\
       \- lib64\
  5. Open the HelloMF2.sln solution in Visual Studio and you are ready to go.

From command line

Start the Visual Studio “x64 Native Tools Command Prompt for VS 20xx”

  1. Prepare a sandbox folder

     set ICU_SANDBOX=%USERPROFILE%\hello_icu_mf2
 md %ICU_SANDBOX%
 cd %ICU_SANDBOX%

  2. Build ICU4C (you only need to do this once):

     git clone https://github.com/unicode-org/icu.git
    
 cd icu\icu4c
 msbuild source/allinone/allinone.sln /p:Configuration=Release /p:Platform=x64 /p:SkipUWP=true
 cd ..\..
    
 set DESTDIR=%ICU_SANDBOX%\icu_release
 rd /q/s %DESTDIR%
 md %DESTDIR%
 xcopy icu\icu4c\include %DESTDIR%\include /E /V /I /Q /Y
 xcopy icu\icu4c\bin64   %DESTDIR%\bin64   /E /V /I /Q /Y
 xcopy icu\icu4c\lib64   %DESTDIR%\lib64   /E /V /I /Q /Y

  3. Create a minimal C++ file here (we are in the $ICU_SANDBOX folder). Call it hello_mf2.cpp. The link to download and the contents are listed above (see the Linux section).

  4. Build your application and run it

     set DESTDIR=%ICU_SANDBOX%\icu_release
 cl /std:c++17 /EHsc /I %DESTDIR%\include %DESTDIR%/lib64/*.lib hello_mf2.cpp
    
 rem set PATH only once, not every time
 set PATH=%DESTDIR%\bin64;%PATH%
    
 .\hello_mf2.exe

    This will output

     Hello John, today is January 28, 2025!

From Visual Studio (UI)

  1. Prepare a sandbox folder. Call it hello_icu_mf2.

  2. Build ICU4C (you only need to do this once)

    • Clone the ICU repository from https://github.com/unicode-org/icu to the hello_icu_mf2 folder. We will end up with the folder hello_icu_mf2\icu.

    • Start Visual Studio.
    • Select “Open a project or solution”
    • Open the allinone.sln solution from the hello_icu_mf2\icu\icu4c\source\allinone folder.
    • Select the “Build” – “Configuration Manager” menu
    • Change the active solution to “Release” and “x64” (or another architecture, but you will have to be consistent everywhere after this)
    • Select the “Build” – “Build solution” menu
    • Select the “File” – “Close solution” menu

  3. Create a minimal C++ project in the hello_icu_mf2 folder. Call it hello_mf2.

    • You are still in Visual Studio. Select “Create a new project”
    • Choose the project template “Console App” (tagged C++, Windows, Console)
    • Click the “Next” button
    • Set the “Project name” to “HelloMF2” and set the “Location” to the hello_icu_mf2 folder. \
    • Click “Create”
    • A project will be created in the hello_icu_mf2\HelloMF2 folder.

  4. Create a macro pointing to the ICU folder with the files we built.

    • Select the “View” – “Property Manager” menu
    • In the new dialog select the root of the tree (“HelloMF2”, not the Debug / Release leafs)
    • Right click and select “Add New Project Property Sheet…”
    • Call it IcuPropertySheet.props and click “Add”
    • Open (double-click) IcuPropertySheet in any of the “leafs” of the tree on the left. For example in HelloMF2 / Release | 64 / IcuPropertySheet
    • Select “User Macros” under “Common Properties” (left tree)
    • Click the “Add Macro” button
    • Name it IcuDistro and set the “Value” to the ..\icu\icu4c folder. If the test project we created is not in hello_icu_mf2, next to icu, then you can use a full path to the ICU folder where you just did a built. You can also point it to one you downloaded (from the GitHub releases, see above).
    • Click the “OK” button

  5. Configure the project

    • Select HelloMF2 in the left-side tree
    • Select the “Project” – “Properties” menu
    • For “Configuration” (top-left) select “All Configurations”
    • For “Platform” (top-right) select “All Platforms”
    • In the left side tree:
      • “C/C++” / “General” set “Additional Include Directories” to $(IcuDistro)\include;%(AdditionalIncludeDirectories)
      • “C/C++” / “Language” set “C++ Language Standard” to ISO C++17 Standard (/std:c++17)
      • “Linker” / “General” set “Additional Dependencies” to
        icudt.lib;icuin.lib;icuuc.lib;$(CoreLibraryDependencies);%(AdditionalDependencies)
      • “Linker” / “General” set “Additional Library Directories” to
        $(IcuDistro)/lib64;%(AdditionalLibraryDirectories)
      • “Debugging” set “Environment” to
        PATH=$(IcuDistro)/bin64;%PATH%
    • For “Platform” (top-right) select “Win32”
    • In the left side tree remove the 64 in two of the settings:
      • “Linker” / “General” set “Additional Library Directories” to
        $(IcuDistro)/lib;%(AdditionalLibraryDirectories)
      • “Debugging” set “Environment” to
        PATH=$(IcuDistro)/bin;%PATH%

  6. Update the default source file to use some ICU functionality

    • Select the “View” – “Solution Explorer” menu
    • In the left-side tree “HelloMF2” / “Source Files” open HelloMF2.cpp
    • Download the hello_mf2.cpp file (see earlier in this page for download link) and save it as HelloMF2.cpp, thereby replacing it.

  7. At this point you should be able to build and run the application, debug it, etc.

  8. When run, it will output

     Hello John, today is January 28, 2025!

Java

We will assume that if you are interested in testing a pre-release Java library you already have (or know how to install) a JDK, Apache Maven, git, know how to create a project in your favorite IDE, and so on.

What you need

  • JDK, any version between 8 and 23
  • Apache Maven

Instructions

  1. Create a new Maven project

     mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=hello_icu_mf2 -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false

 cd hello_icu_mf2

  2. Modify the pom.xml file

    1. The project created as above uses the Java 17 version. If you are using a lower version then change <maven.compiler.release> property to whatever Java version you are using. 
       # Example on how to set the Java version to 11
 mvn versions:set-property -Dproperty=maven.compiler.release -DnewVersion=11
    2. Edit the file and add this to <dependencies> 
       <dependency>
   <groupId>com.ibm.icu</groupId>
   <artifactId>icu4j</artifactId>
   <version>77.0.1-SNAPSHOT</version>
 </dependency>

      Warning: make sure it is done in dependencies, not in dependencyManagement / dependencies

  3. Edit the src/test/java/com/mycompany/app/AppTest.java file

    1. Add a new test method 
       @Test
 public void testMessageFormat2() {
     MessageFormatter mf2 = MessageFormatter.builder()
             .setLocale(Locale.US)
             .setPattern("Hello {$user}, today is {$now :date style=long}!")
             .build();
     Calendar cal = Calendar.getInstance();
     cal.set(2025, 0, 28);
 
     Map<String, Object> arguments = new HashMap<>();
     arguments.put("user", "John");
     arguments.put("now", cal);
     System.out.println(mf2.formatToString(arguments));
 }

    2. Add imports

       import java.util.HashMap;
 import java.util.Locale;
 import java.util.Map;
 import com.ibm.icu.util.Calendar;
 import com.ibm.icu.message2.MessageFormatter;

  4. Now run the tests

     mvn package -q

    This will output the following in the the tests’ console output

     Hello John, today is January 28, 2025!