Improve handling of the '@' Character in Translations

[wnmzzzz]

Clear and concise description of the problem

The '@' Character in translations is a special Character since v9. However, '@' is also a common literal that appears in things like Emails. Including the literal '@' in a translation requires cubbersome and unintuitive literal interpolation.

On top of that, translations are sometimes not written by the developers themselves, but by third party translators that do not have a grounded technical background and might not understand why they cannot simply write what they want it to say.

You can tell how often people stumble upon this by taking a look at the discussion in #531 or #118

Suggested solution

It should be possible to freely chose the special character to use for linking, so that a developer can pick a symbol or series of symbols that's unlikely to appear in their messages. This could be done via a configuration option, with '@' remaining the default to maintain backwards compatibility.

Alternative

It should also be possible to completely disable this linking feature for simple use-cases that do not make use of the @ functionality.

Additional context

While there was a lot of discussion in #531 about this, that issue is a closed Bug report, while this is a feature request. As such, I hope this does not count as a duplicate issue.

Validations

• Read the Contributing Guidelines
• Read the Documentation
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[yanickrochon]

I actually got into the same issue, yesterday, and I have been trying to get around this. Why isn't the interpolation working like String templates? LIke:

export default {
    'common.domain': '@domain.com',

    'form.field.email.placeholder': 'user@{common.domain}',
}

Where the pattern @{...} is searched instead of stopping at @.

Edit

After reading all the comments and various solutions, I have tried

export default {
    'form.field.email.placeholder': "user{'@'}domain.com",
}

So, really, there already is support for {...}. So the question becomes: Why not using this pattern for linked messages instead adding a new complexity?

export default {
    'common.domain': '@domain.com',

    'form.field.email.placeholder.literal': 'user@domain.com',
    'form.field.email.placeholder.linked': 'user{common.domain}',
    'form.field.email.placeholder.string': "user{'@domain.com'}",
}

[v-rudkovskiy]

I'd like to share my feedback on linked messages and @ handling after upgrading vue-i18n from v8 (Vue 2) to v11 (Vue 3).

Problem 1: Linked messages broken with trailing quotes

In v8, this pattern worked perfectly:

{
  "tooltip": "Click on \"@:buttons.create\" to add a new item."
}

In v11, the parser seems to misinterpret the closing quote and tries to resolve a key like buttons.create" instead of buttons.create, which results in missing or broken links.

The only workaround I’ve found is using the function syntax:

tooltip: ({ linked }) =>
  `Click on "${linked('buttons.create')}" to add a new item.`,

While functional, this workaround is verbose and discourages using flat JSON for localization — especially problematic for translation workflows.

Problem 2: @ used as a regular character now causes parsing errors

Another issue: strings that include @ — such as email addresses — now throw compilation errors even though they’re not meant to be linked messages:

{
  "notice": "Contact us at help@example.com"
}

Error:

Message compilation error: Invalid linked format
1  |  Contact us at help@example.com

Current workarounds like this feel awkward and unnatural:

{
  "notice": "Contact us at help{'@'}example.com"
}

Suggested Solution

To address both issues, I propose introducing a clear and unambiguous syntax for linked keys, such as:

{
  "tooltip": "Click on {@:buttons.create} to add a new item."
}

This format:

• Clearly defines the start and end of a linked key.
• Avoids accidental parsing of @ in normal text (e.g., email addresses).
• Reduces reliance on escaping or verbose function syntax.
• Preserves compatibility with flat translation files and external tools.

[form1c]

We had the same challenge. If you don't need the @ symbol for linking, one solution could be to replace the @ symbol with a literal string using a messageResolver.

const i18n = VueI18n.createI18n({
…
  messageResolver: (messages, path) => {
    const msg = messages[path];
    if (typeof msg === 'string') {
      return msg.replaceAll(/@/g, "{'@'}")
    }
    return msg
  },
  messages: { }
})

[yanickrochon]

The challenge is this:

• prevent misinterpretations of literals in translation strings, because "email@domain" is a typical use case and "email{'@'}domain" is but a hack;
• differentiate named arguments from my linked messages;
• avoid introducing a different syntax, for example keep the bracket ("{}") notation;
• both linked messages, and named arguments must be usable inside JSON localisation files.

On short, the problem boils down to this: how to differentiate between names arguments and linked messages?

So, if

• "message" is a translation string,
• '{'literal'}" is a string literal
• "{named}" is a named argument

The logical solution is to also use brackets for linked messages, but different enough as to not create confusion with named arguments.

Suggestions :

• "{@foo.bar}", I.e. wrap the current "@foo.bar" inside brackets;
• "{{foo.bar}}", i.e. use double brackets for linked substitution with foo.bar message key;:
• "\\@foo.bar", i.e. inform the message resolver that the @ is an escape character ("\\" becomes a single backslash once evaluated by the engine, whether JavaScript or JSON).

Of course, another question may arise: What if I have a translation string where "{n}" should be evaluated as a literal, i.e. literally be to display "{n}", and not be evaluated as expecting a named argument n to be provided?

In that case, having "{@linked}" for linked messages and "{$named}" for names arguments is homogeneous and standard.

The message resolver, then, simply needs to match patterns surrounded by brackets, with a recognized character. Then enabling the configuration of these characters through substitution resolvers.

For example, $ is associated with named arguments resolver, and @ is associated with the linked messages resolver, so a message "Hello {$name}, you have {@user.notifications}" sends "name" to the named arguments substitution, and "user.notifications" to the linked messages substitution.

To me, this syntax is clear and concise. And if someone has, for some twisted reason, a need to have either {$ or {@ in their locale messages, then "{'{@'}" can be used. Since occurrences of those are even less frequent than using brackets otherwise, this is a marginal case at best.