Lingui translation API function in pure JS (without macro)

[MurzNN]

Could anyone share an example of the Lingui translation function without macro, in pure JS? Something like this:

import { I18n } from '@lingui/core'

i18n.load("fr", messages)
i18n.activate("fr")
const translated = i18n.SOMETHING('Hello world')

So, what should be used instead of SOMETHING to get the result?

[MurzNN]

I still can't find a short alternative for this, only composed a long one with a custom function like this:

import { I18n } from '@lingui/core'
import { generateMessageId } from "@lingui/message-utils/generateMessageId"

i18n.load("fr", messages)
i18n.activate("fr")
function linguiMsg(message) {
  return { id: generateMessageId(message), message };
}
const translated = i18n._(linguiMsg("Hello world"));

Is there any API function exist that does this in a simpler way?

[timofei-iatsenko]

const translated = i18n._({id: 'app.heading',  'Hello world'})

Once you ditch the macro you will have to craft ids by yourself. The code you created in the previous message

function linguiMsg(message) {
  return { id: generateMessageId(message), message };
}
const translated = i18n._(linguiMsg("Hello world"));

would not be recognized by the extractor.

[MurzNN]

Thank you! Seems the most convenient way in places where we can't use the t macro - is to still use the msg macro like this:

import { I18n } from '@lingui/core'
import { msg } from '@lingui/core/macro'

i18n.load("fr", messages)
i18n.activate("fr")
const translated = i18n._(msg`Hello world`)

This works as required for cases when you have the i18n object defined as a local object, not the global one, like this:

const { allI18nInstances } = await initializeI18n()

export function myFunction(locale: string) {
  const i18n = allI18nInstances[locale]
  const translated = i18n._(msg`Hello world`)
}

[MurzNN]

And if you need to use the strings with a custom id, here is an invented approach:

const { allI18nInstances } = await initializeI18n()

export function myFunction(locale: string) {
  const i18n = allI18nInstances[locale]
  const translated = i18n._(
        msg({
          id: 'subjectOnDomain',
          message: `{subject} on {domain}`,
        }).id,
        {
          subject: 'foo',
          domain: 'bar',
        })
}
``

[timofei-iatsenko]

Yes using msg together with i18n._(msg`Hello world`) is recomended approach.

Regarding custom id you probably could simplify this to just (if you have subject and domain already available):

const translated = i18n._(msg({
    id: 'subjectOnDomain',
    message: `${{subject}} on ${{domain}}`,
}))

[MurzNN]

Oh, the issue is that we can't use any macros in pure JS, so using the msg macro leads to issues like this: #2469 - have to revert back to the raw implementation like this:

const translated = this.i18n._(
  `{subject} on {domain}`,
  {
    subject: 'foo',
    domain: 'bar,
  },
)

So, still searching for the right clean solution...

[MurzNN]

After trying different approaches, I settled on this the most simple and clean approach of translating messages in pure JS without macros:

const text = i18n.t(/* i18n */ '{subject} on {domain}', {
  subject: 'foo',
  domain: 'bar,
})

It works well and using the /* i18n */ comment, the extractor detects and extracts the string correctly. The issue is only with complex scenarios where I need to pass the context to the message, for this I created a separate question: #2490

[MurzNN]

Finally invented a pure JS reusable translation function ts() (translate string):

import { i18n } from '@lingui/core'
import { generateMessageId } from '@lingui/message-utils/generateMessageId'

/**
 * Translates a variable string using Lingui.
 *
 * This function generates a message ID from the input string and context,
 * then translates it using the Lingui i18n instance. If no translation is found
 * (indicated by a 6-character alphanumeric result), it returns the original string
 * as a fallback and logs a warning.
 *
 * @param str - The message string to translate
 * @param values - Optional values for interpolation (same as i18n.t)
 * @param options - Optional translation options, including:
 *   - `context`: Optional context string used for message ID generation to disambiguate translations
 *   - Other options passed to i18n.t (same as i18n.t)
 * @returns The translated string, or the original string if translation is missing
 *
 * @example
 * // Simple translation
 * ts(/* i18n *\/ 'Hello')
 *
 * @example
 * // With interpolation
 * ts(/* i18n *\/ 'Hello {name}', { name: 'John' })
 *
 * @example
 * // With context for disambiguation
 * ts('Right', { context: 'direction' })
 * Warning: defining messages with context using `/* i18n *\/` does not work
 * with Lingui extractor, so you still have to define them manually somewhere
 * in the code using a macro:
 * ```
 * import { defineMessage } from '@lingui/core/macro'
 * defineMessage({message: 'Right', context: 'direction'})
 * ```
 */
export const ts = (
  str: string,
  values?: Parameters<typeof i18n.t>[1],
  options?: Parameters<typeof i18n.t>[2] & { context?: string },
): string => {
  const msgId = generateMessageId(str, options?.context)
  const result = i18n.t(msgId, values, options)
  if (result.length === 6 && result.match(/^[a-zA-Z0-9]{6}$/)) {
    // If the result is a 6-character alphanumeric string, it means the translation is missing.
    // Return the original string as a fallback.
    console.warn(
      `Missing translation for message "${str}" (id '${msgId}'). Returning original string as fallback.`,
    )
    return str
  }
  return result
}

[MurzNN]

The extractor still adds the #. js-lingui-explicit-id comment to the strings, extracted from the /* i18n */ comment, a workaround is to manually delete them from the generated .po files.

Still trying to find an easy way to extend the extractor to make this work automatically.

So, the idea is to introduce a new comment /* i18n-str */ for strings that will be extracted and converted to the id, and an option to the extractor to set this mode for the /* i18n */ comments globally.

[MurzNN]

Another workaround is creating a custom script that finds all messages in the code and generates a separate file with definitions like this:

const message1 = /** i18n */ {
  id: "mY42CM",
  message: "Hello World",
};

[MurzNN]

Created a PR that allows defining strings with generated IDs using comments /* i18n-s */ - #2586