The Checker Framework Manual:
Custom pluggable types for Java

Chapter 16 Internationalization Format String Checker (I18n Format String Checker)

The Internationalization Format String Checker, or I18n Format String Checker, prevents use of incorrect i18n format strings.

If the I18n Format String Checker issues no warnings or errors, then MessageFormat.format will raise no error at run time. “I18n” is short for “internationalization” because there are 18 characters between the “i” and the “n”.

Here are examples of errors that the I18n Format Checker detects at compile time.

    // Warning: the second argument is missing.
    MessageFormat.format("{0} {1}", 3.1415);
    // String argument cannot be formatted as Time type.
    MessageFormat.format("{0, time}", "my string");
    // Invalid format string: unknown format type: thyme.
    MessageFormat.format("{0, thyme}", new Date());
    // Invalid format string: missing the right brace.
    MessageFormat.format("{0", new Date());
    // Invalid format string: the argument index is not an integer.
    MessageFormat.format("{0.2, time}", new Date());
    // Invalid format string: "#.#.#" subformat is invalid.
    MessageFormat.format("{0, number, #.#.#}", 3.1415);

For instructions on how to run the Internationalization Format String Checker, see Section 16.6.

The Internationalization Checker or I18n Checker (Section 17.2) has a different purpose. It verifies that your code is properly internationalized: any user-visible text should be obtained from a localization resource and all keys exist in that resource.

The paper “A type system for format strings” [WKSE14] (ISSTA 2014, https://homes.cs.washington.edu/~mernst/pubs/format-string-issta2014-abstract.html) gives more details about the Internationalization Format String Checker and the Format String Checker (Chapter 15).

16.1 Internationalization Format String Checker annotations

The MessageFormat documentation specifies the syntax of the i18n format string.

These are the qualifiers that make up the I18n Format String type system. Figure 16.1 shows their subtyping relationships.

@I18nFormat

represents a valid i18n format string. For example, @I18nFormat({GENERAL, NUMBER, UNUSED, DATE}) is a legal type for "{0}{1, number} {3, date}", indicating that when the format string is used, the first argument should be of GENERAL conversion category, the second argument should be of NUMBER conversion category, and so on. Conversion categories such as GENERAL are described in Section 16.2.

@I18nFormatFor

indicates that the qualified type is a valid i18n format string for use with some array of values. For example, @I18nFormatFor("#2") indicates that the string can be used to format the contents of the second parameter array. The argument is a Java expression whose syntax is explained in Section 33.8. An example of its use is:

    static void method(@I18nFormatFor("#2") String format, Object... args) {
      // the body may use the parameters like this:
      MessageFormat.format(format, args);
    }

    method("{0, number} {1}", 3.1415, "A string"); // OK
    // error: The string "hello" cannot be formatted as a Number.
    method("{0, number} {1}", "hello", "goodbye");

@I18nInvalidFormat

represents an invalid i18n format string. Programmers are not allowed to write this annotation. It is only used internally by the type checker.

@I18nUnknownFormat

represents any string. The string might or might not be a valid i18n format string. Programmers are not allowed to write this annotation.

@I18nFormatBottom

indicates that the value is definitely null. Programmers are not allowed to write this annotation.

16.2 Conversion categories

In a message string, the optional second element within the curly braces is called a format type and must be one of number, date, time, or choice. These four format types correspond to different conversion categories. date and time correspond to DATE in the conversion categories figure. choice corresponds to NUMBER. The format type restricts what arguments are legal. For example, a date argument is not compatible with the number format type, i.e., MessageFormat.format("{0, number}", new Date()) will throw an exception.

The I18n Checker represents the possible arguments via conversion categories. A conversion category defines a set of restrictions or a subtyping rule.

Figure 16.2 summarizes the subset relationship among all conversion categories.

16.3 Subtyping rules for `@I18nFormat`

Here are the subtyping rules among different @I18nFormat qualifiers. It is legal to:

• use a format string with a weaker (less restrictive) conversion category than required.
• use a format string with fewer format specifiers than required. Although this is legal, a warning is issued because most occurrences of this are due to programmer error.

The following example shows the subtyping rules in action:

    @I18nFormat({NUMBER, DATE}) String f;

    f   =   "{0, number, #.#} {1, date}";   //   OK
    f   =   "{0, number} {1}";              //   OK, GENERAL is weaker (less restrictive) than DATE
    f   =   "{0} {1, date}";                //   OK, GENERAL is weaker (less restrictive) than NUMBER
    f   =   "{0, number}";                  //   warning: last argument is ignored
    f   =   "{0}";                          //   warning: last argument is ignored
    f   =   "{0, number} {1, number}";      //   error: NUMBER is stronger (more restrictive) than DATE
    f   =   "{0} {1} {2}";                  //   error: too many arguments

The conversion categories are:

UNUSED

indicates an unused argument. For example, in MessageFormat.format("{0, number} {2, number}", 3.14, "Hello", 2.718), the second argument Hello is unused. Thus, the conversion categories for the format, {0, number} {2, number}, are (NUMBER, UNUSED, NUMBER).

GENERAL

means that any value can be supplied as an argument.

DATE

is applicable for date, time, and number types. An argument needs to be of Date or Number type or a subclass of them, including Time, Timestamp, and the classes listed immediately below.

NUMBER

means that the argument needs to be of Number type or a subclass: Number, AtomicInteger, AtomicLong, BigDecimal, BigInteger, Byte, Double, Float, Integer, Long, Short.

16.4 What the Internationalization Format String Checker checks

The Internationalization Format String Checker checks calls to the i18n formatting method MessageFormat.format and guarantees the following:

1. The checker issues a warning for the following cases:
- (a) There are missing arguments from what is required by the format string.
  
  MessageFormat.format("{0, number} {1, number}", 3.14); // Output: 3.14 {1}
- (b) More arguments are passed than what is required by the format string.
  
  MessageFormat.format("{0, number}", 1, new Date());
  
  MessageFormat.format("{0, number} {0, number}", 3.14, 3.14);
  
  This does not cause an error at run time, but it often indicates a programmer mistake. If it is intentional, then you should suppress the warning (see Chapter 34).
- (c) Some argument is an array of objects.
  
  MessageFormat.format("{0, number} {1}", array);
  
  The checker cannot verify whether the format string is valid, so the checker conservatively issues a warning. This is a limitation of the Internationalization Format String Checker.
2. The checker issues an error for the following cases:
- (a) The format string is invalid.
  - • Unmatched braces.
    
    MessageFormat.format("{0, time", new Date());
  - • The argument index is not an integer or is negative.
    
    MessageFormat.format("{0.2, time}", new Date());
    
    MessageFormat.format("{-1, time}", new Date());
  - • Unknown format type.
    
    MessageFormat.format("{0, foo}", 3.14);
  - • Missing a format style required for choice format.
    
    MessageFormat.format("{0, choice}", 3.14);
  - • Wrong format style.
    
    MessageFormat.format("{0, time, number}", 3.14);
  - • Invalid subformats.
    
    MessageFormat.format("{0, number, #.#.#}", 3.14)
- (b) Some argument’s type doesn’t satisfy its conversion category.
  
  MessageFormat.format("{0, number}", new Date());

The checker also detects illegal assignments: assigning a non-format-string or an incompatible format string to a variable declared as containing a specific type of format string. For example,

    @I18nFormat({GENERAL, NUMBER}) String format;
    // OK.
    format = "{0} {1, number}";
    // OK, GENERAL is weaker (less restrictive) than NUMBER.
    format = "{0} {1}";
    // OK, it is legal to have fewer arguments than required (less restrictive).
    // But a warning will be issued.
    format = "{0}";

    // Error, the   format string has too many arguments.
    format = "{0}   {1} {2}";
    // Error, the   format string is more restrictive. NUMBER is a subtype of GENERAL.
    format = "{0,   number} {1, number}";

16.5 Resource files

A programmer rarely writes an i18n format string literally. (The examples in this chapter show that for simplicity.) Rather, the i18n format strings are read from a resource file. The program chooses a resource file at run time depending on the locale (for example, different resource files for English and Spanish users).

For example, suppose that the resource1.properties file contains

    key1 = The number is {0, number}.

Then code such as the following:

    String formatPattern = ResourceBundle.getBundle("resource1").getString("key1");
    System.out.println(MessageFormat.format(formatPattern, 2.2361));

will output “The number is 2.2361.” A different resource file would contain key1 = El número es {0, number}.

When you run the I18n Format String Checker, you need to indicate which resource file it should check. If you change the resource file or use a different resource file, you should re-run the checker to ensure that you did not make an error. The I18n Format String Checker supports two types of resource files: ResourceBundles and property files. The example above shows use of resource bundles. For more about checking property files, see Chapter 17.

16.6 Running the Internationalization Format Checker

The checker can be invoked by running one of the following commands (with the whole command on one line).

• Using ResourceBundles:

javac -processor org.checkerframework.checker.i18nformatter.I18nFormatterChecker -Abundlenames=MyResource MyFile.java
• Using property files:

javac -processor org.checkerframework.checker.i18nformatter.I18nFormatterChecker -Apropfiles=MyResource.properties MyFile.java
• Not using a property file. Use this if the programmer hard-coded the format patterns without loading them from a property file.

javac -processor org.checkerframework.checker.i18nformatter.I18nFormatterChecker MyFile.java

16.7 Testing whether a string has an i18n format type

In the case that the checker cannot infer the i18n format type of a string, you can use the I18nFormatUtil.hasFormat method to define the type of the string in the scope of a conditional statement.

I18nFormatUtil.hasFormat

returns true if the given string has the given i18n format type.

For an example, see Section 16.8.

To use the I18nFormatUtil class, the checker-util.jar file must be on the classpath at run time.

16.8 Examples of using the Internationalization Format Checker

• Using MessageFormat.format.

        // suppose the bundle "MyResource" contains: key1={0, number} {1, date}
        String value = ResourceBundle.getBundle("MyResource").getString("key1");
        MessageFormat.format(value, 3.14, new Date()); // OK
        // error: incompatible types in argument; found String, expected number
        MessageFormat.format(value, "Text", new Date());

• Using the I18nFormatUtil.hasFormat method to check whether a format string has particular conversion categories.

        void test1(String format) {
          if (I18nFormatUtil.hasFormat(format, I18nConversionCategory.GENERAL,
                                               I18nConversionCategory.NUMBER)) {
            MessageFormat.format(format, "Hello", 3.14); // OK
            // error: incompatible types in argument; found String, expected number
            MessageFormat.format(format, "Hello", "Bye");
            // error: missing arguments; expected 2 but 1 given
            MessageFormat.format(format, "Bye");
            // error: too many arguments; expected 2 but 3 given
            MessageFormat.format(format, "A String", 3.14, 3.14);
          }
        }

• Using @I18nFormatFor to ensure that an argument is a particular type of format string.

        static void method(@I18nFormatFor("#2") String f, Object... args) {...}

        // OK, MessageFormat.format(...) would return "3.14 Hello greater than one"
        method("{0, number} {1} {2, choice,0#zero|1#one|1<greater than one}",
               3.14, "Hello", 100);

        // error: incompatible types in argument; found String, expected number
        method("{0, number} {1}", "Bye", "Bye");

• Annotating a string with @I18nFormat.

        @I18nFormat({I18nConversionCategory.DATE}) String s1;
        s1 = "{0}";
        s1 = "{0, number}";        // error: incompatible types in assignment

The Checker Framework Manual: Custom pluggable types for Java