Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The MessageFormat class

Reference for java.text.MessageFormat: numbered placeholders, number formats, choice patterns for plurals, apostrophe quoting rules and parsing messages.

java.text.MessageFormat builds text from a template with numbered placeholders such as and . Unlike printf, the placeholders are positional by number, not by order of appearance, which is what translators need: a translated sentence can put the arguments in a different order without changing the code.

A placeholder can carry a format type and style: {0,number,percent}, {1,number,#.##}, {2,choice,...}. Numbers are formatted with the locale, and each argument is converted by an appropriate Format object. This is the format used by Java resource bundles for parameterized messages.

Java
MessageFormat.format("{1} bought {0} apples", 3, "Ann");   // "Ann bought 3 apples"

Try it

Java Placeholders, number styles and choice

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Apostrophes, quoting and parsing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

TEXT
{ArgumentIndex}
{ArgumentIndex,FormatType}
{ArgumentIndex,FormatType,FormatStyle}
FormatType FormatStyle Result
(none) strings as is; numbers with NumberFormat.getInstance; dates with DateFormat; other objects with toString()
number integer, currency, percent, or a DecimalFormat pattern number formatting
date, time short, medium, long, full, or a SimpleDateFormat pattern date or time formatting for java.util.Date arguments
choice a ChoiceFormat pattern such as `0#none 1#one
Java
public class MessageFormat extends Format
public MessageFormat(String pattern)
public MessageFormat(String pattern, Locale locale)
public static String format(String pattern, Object... arguments)
public final StringBuffer format(Object[] arguments, StringBuffer result, FieldPosition pos)
public Object[] parse(String source) throws ParseException
Parameter Description
pattern the template; a single quote starts quoted text, '' is a literal quote
locale locale used for numbers and dates; the static format uses the default one
arguments values for , , ...

Returns: the formatted string (or Object[] from parse). Throws: IllegalArgumentException for a malformed pattern or if the argument is not an array; ParseException from parse.

Usage notes

  • Apostrophes are the classic trap. In the pattern "It's {0}" the apostrophe opens a quote, so the output is Its {0}. Write '' for a literal apostrophe. This also applies to translations in resource bundles that go through MessageFormat.
  • Quoting braces. '{' and '}' produce literal braces.
  • Dates and times need java.util.Date (or Calendar) arguments; java.time objects are not recognized by the date type. Format those yourself with DateTimeFormatter and pass the string.
  • Missing arguments leave the placeholder text as written (); a null argument prints null; extra arguments are ignored.
  • Choice patterns use # for "this limit or above" and < for "greater than the limit"; the limits must be in ascending order. Nesting {0,number,integer} inside a choice text prints the argument again.
  • Not thread-safe. Instances hold mutable state; the static format method is safe because it creates a new object each time, at the cost of parsing the pattern on every call.
  • For plural-aware messages with many languages, ChoiceFormat is limited (it cannot express rules like Polish or Arabic plurals). Libraries built on ICU provide full plural rules.
  • Choose the tool. Use String.format for developer-facing text and MessageFormat when messages are externalized and may be reordered by translators.