Feature Request: Support fallback text in `$t` function signature

[icai]

Clear and concise description of the problem

Currently, the $t function in Vue I18n supports the following signatures:

$t(key: string): string;
$t(key: string, values?: Record<string, unknown>): string;

However, it does not support a fallback text as the second parameter. This leads to confusion when developers attempt to write:

$t('submit.button', 'Submit'); // This does NOT work — it treats 'Submit' as values

This is a common intuitive usage pattern for developers coming from other i18n libraries (e.g., i18next).

Suggested solution

Proposal

Extend the $t function to support the following overloaded signatures:

function $t(key: string): string;
function $t(key: string, fallback: string): string;
function $t(key: string, values: Record<string, unknown>): string;
function $t(key: string, values: Record<string, unknown>, fallback: string): string;

With this behavior:

• If the second argument is a string, treat it as a fallback text.
• If the second argument is an object, treat it as interpolation values.
• If the key is not found in the current or fallback locale(s), return the fallback string if provided.

Example

$t('common.ok', 'OK')                          // fallback = "OK"
$t('user.greet', { name: 'John' })             // interpolation
$t('user.greet', { name: 'John' }, 'Hi John')  // interpolation + fallback

This would greatly improve DX (Developer Experience) and simplify many use-cases where fallback strings are needed inline.

Workaround

We can currently implement a wrapper manually:

function $tSmart(
  key: string,
  valuesOrFallback?: Record<string, unknown> | string,
  fallback?: string
): string {
  const result = t(key, typeof valuesOrFallback === 'object' ? valuesOrFallback : undefined);
  return result === key
    ? typeof valuesOrFallback === 'string'
      ? valuesOrFallback
      : fallback ?? key
    : result;
}

But this requires additional setup and breaks typing.

Why This Matters

This small enhancement would:

• Align with developer expectations
• Reduce boilerplate fallback handling
• Maintain full backward compatibility

Thank you for your excellent work on Vue I18n!

Alternative

No response

Additional context

No response

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.

[s3xysteak]

PUSH

When using like:

$t(`a.b.${key}.c`)

it is annoying that I have to do like:

$t(`a.b.${key}.c`) === `a.b.${key}.c` ? 'fallback word' : $t(`a.b.${key}.c`)

Or using a helper function like the issue author said.