Overview

The msg function marks and encodes strings for translation.

const encodedString = msg('Hello, world!');

The encoded string should be passed to the useMessages hook or getMessages function to retrieve translations.

Decoding

To retrieve the original string, decode it with decodeMsg

import { msg, decodeMsg } from 'gt-next';
const encodedString = msg('Hello, world!');
const decodedString = decodeMsg(encodedString);
console.log(decodedString); // "Hello, world!"

Reference

Parameters

Returns

An encoded string with any interpolated variables replaced by their values.

Behaviour

Production

During the CD process, any content inside a msg function will be translated before your application is deployed. This ensures fast load times for all locales, but it can only translate content known at build time.

Once generated, translations are either (1) stored on the CDN or (2) included in your app’s build output, according to your configuration. From there, the translated content is served to your users. If a translation isn’t found, it will fall back to the original content.

Make sure to follow the deployment guide here.

Development

During development, the msg function will translate content on demand. This is useful for prototyping what your app will look like in different languages. Remember to add a Dev API key to your environment to enable this behaviour.

You will see a delay during on-demand translation in development. This will not occur for production builds unless content is explicitly being translated on demand, i.e., using tx or <Tx>.

Example

Basic Usage

You can use msg to mark strings for translation.

import { msg, useMessages } from 'gt-next';

const encodedString = msg('Hello, world!');

export default function TranslateGreeting() {
  const m = useMessages();
  return (
    <p>
      {m(encodedString)}
    </p>
  );
}

Note: "Hello, world!" will be translated into the user's preferred language.

Using variables

You can pass variables into dictionary translations.

import { msg, useMessages } from 'gt-next';

const encodedString = msg('Hello, {name}!', { name: 'Alice' });

export default function TranslateGreeting() {
  const m = useMessages();

  return (
    <p>
      {m(encodedString)}
    </p>
  );
}

Note: "Alice" will not be translated into the user's preferred language because it is a variable.

Using the ICU message format

gt-next supports the ICU message format, which also lets you format your variables.

import { msg, useMessages } from 'gt-next';

const encodedString = msg('There are {count, plural, =0 {no items} =1 {one item} other {{count} items}} in the basket', { count: 10 });

export default function TranslateGreeting() {
  const m = useMessages();
  return (
    <p>
      {m(encodedString)}
    </p>
  );
}

Notes

• The msg function marks strings for translation.
• Strings marked with msg are processed before runtime, during the build (unless in development).

Next steps

• See useMessages for translating strings.
• See getMessages for translating strings in asynchronous server‑side components.