Skip to content

Commit ee1a2a9

Browse files
tholanderThéo Holanderamannn
authored
feat: Add t.has to check whether a given message exists (#1399)
 Co-authored-by: Théo Holander <theo.holander@reflet-digital.com> Co-authored-by: Jan Amann <jan@amann.work>
1 parent 04d7263 commit ee1a2a9

File tree

12 files changed

+164
-6
lines changed

12 files changed

+164
-6
lines changed

‎docs/pages/docs/usage/messages.mdx

+13
Original file line numberDiff line numberDiff line change
@@ -453,6 +453,19 @@ Messages are always parsed and therefore e.g. for rich text formatting you need
453453

454454
The value of a raw message can be any valid JSON value: strings, booleans, objects and arrays.
455455

456+
## Optional messages [#t-has]
457+
458+
If you have messages that are only available for certain locales, you can use the `t.has` function to check whether a message is available for the current locale:
459+
460+
```js
461+
const t = useTranslations('About');
462+
463+
t.has('title'); // true
464+
t.has('unknown'); // false
465+
```
466+
467+
Note that separately from this, you can also provide [fallback messages](/docs/usage/configuration#messages-fallback), e.g. from the default locale, in case you have incomplete messages for certain locales.
468+
456469
## Arrays of messages
457470

458471
If you need to render a list of messages, the recommended approach is to map an array of keys to the corresponding messages:

‎examples/example-app-router-playground/src/app/[locale]/page.tsx

+1
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ export default function Index({searchParams}: Props) {
5555
</div>
5656
<ClientLink href="/">Link on client without provider</ClientLink>
5757
<p data-testid="SearchParams">{JSON.stringify(searchParams, null, 2)}</p>
58+
<p data-testid="HasTitle">{JSON.stringify(t.has('title'))}</p>
5859
<Image alt="" height={77} priority src="/assets/image.jpg" width={128} />
5960
<AsyncComponent />
6061
<AsyncComponentWithNamespaceAndLocale />

‎examples/example-app-router-playground/src/components/AsyncComponent.tsx

+10
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ export default async function AsyncComponent() {
88
<p>{t('basic')}</p>
99
<p>{t.rich('rich', {important: (chunks) => <b>{chunks}</b>})}</p>
1010
<p>{t.markup('markup', {b: (chunks) => `<b>${chunks}</b>`})}</p>
11+
<p>{String(t.has('basic'))}</p>
1112
</div>
1213
);
1314
}
@@ -23,6 +24,15 @@ export async function TypeTest() {
2324
// @ts-expect-error
2425
t('unknown');
2526

27+
// @ts-expect-error
28+
t.rich('unknown');
29+
30+
// @ts-expect-error
31+
t.markup('unknown');
32+
33+
// @ts-expect-error
34+
t.has('unknown');
35+
2636
format.dateTime(new Date(), 'medium');
2737
// @ts-expect-error
2838
format.dateTime(new Date(), 'unknown');

‎examples/example-app-router-playground/tests/main.spec.ts

+5
Original file line numberDiff line numberDiff line change
@@ -697,6 +697,11 @@ it('can use `getPahname` to define a canonical link', async ({page}) => {
697697
await expect(getCanonicalPathname()).resolves.toBe('/de/neuigkeiten/3');
698698
});
699699

700+
it('can use `t.has` in a Server Component', async ({page}) => {
701+
await page.goto('/');
702+
await expect(page.getByTestId('HasTitle')).toHaveText('true');
703+
});
704+
700705
describe('server actions', () => {
701706
it('can use `getTranslations` in server actions', async ({page}) => {
702707
await page.goto('/actions');

‎packages/next-intl/.size-limit.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ const config: SizeLimitConfig = [
1515
},
1616
{
1717
path: 'dist/production/navigation.react-server.js',
18-
limit: '15.845 KB'
18+
limit: '15.89 KB'
1919
},
2020
{
2121
path: 'dist/production/server.react-client.js',

‎packages/next-intl/src/react-server/getTranslator.tsx

+18
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,24 @@ function getTranslatorImpl<
9898
>(
9999
key: TargetKey
100100
): any;
101+
102+
// `has`
103+
has<
104+
TargetKey extends MessageKeys<
105+
NestedValueOf<
106+
{'!': IntlMessages},
107+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
108+
>,
109+
NestedKeyOf<
110+
NestedValueOf<
111+
{'!': IntlMessages},
112+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
113+
>
114+
>
115+
>
116+
>(
117+
key: TargetKey
118+
): boolean;
101119
} {
102120
return createTranslator({
103121
...config,

‎packages/next-intl/src/server/react-server/getTranslations.tsx

+18
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,24 @@ Promise<{
103103
>(
104104
key: [TargetKey] extends [never] ? string : TargetKey
105105
): any;
106+
107+
// `has`
108+
has<
109+
TargetKey extends MessageKeys<
110+
NestedValueOf<
111+
{'!': IntlMessages},
112+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
113+
>,
114+
NestedKeyOf<
115+
NestedValueOf<
116+
{'!': IntlMessages},
117+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
118+
>
119+
>
120+
>
121+
>(
122+
key: [TargetKey] extends [never] ? string : TargetKey
123+
): boolean;
106124
}>;
107125
// CALL SIGNATURE 2: `getTranslations({locale, namespace})`
108126
function getTranslations<

‎packages/use-intl/.size-limit.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ const config: SizeLimitConfig = [
55
name: './ (ESM)',
66
import: '*',
77
path: 'dist/esm/index.js',
8-
limit: '14.085 kB'
8+
limit: '14.095 kB'
99
},
1010
{
1111
name: './ (no useTranslations, ESM)',

‎packages/use-intl/src/core/createBaseTranslator.tsx

+17-2
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,8 @@ function createBaseTranslatorImpl<
205205
onError,
206206
timeZone
207207
}: CreateBaseTranslatorProps<Messages>) {
208+
const hasMessagesError = messagesOrError instanceof IntlError;
209+
208210
function getFallbackFromErrorAndNotify(
209211
key: string,
210212
code: IntlErrorCode,
@@ -223,7 +225,7 @@ function createBaseTranslatorImpl<
223225
/** Provide custom formats for numbers, dates and times. */
224226
formats?: Formats
225227
): string | ReactElement | ReactNodeArray {
226-
if (messagesOrError instanceof IntlError) {
228+
if (hasMessagesError) {
227229
// We have already warned about this during render
228230
return getMessageFallback({
229231
error: messagesOrError,
@@ -419,7 +421,7 @@ function createBaseTranslatorImpl<
419421
/** Use a dot to indicate a level of nesting (e.g. `namespace.nestedLabel`). */
420422
key: string
421423
): any => {
422-
if (messagesOrError instanceof IntlError) {
424+
if (hasMessagesError) {
423425
// We have already warned about this during render
424426
return getMessageFallback({
425427
error: messagesOrError,
@@ -440,5 +442,18 @@ function createBaseTranslatorImpl<
440442
}
441443
};
442444

445+
translateFn.has = (key: Parameters<typeof translateBaseFn>[0]): boolean => {
446+
if (hasMessagesError) {
447+
return false;
448+
}
449+
450+
try {
451+
resolvePath(locale, messagesOrError, key, namespace);
452+
return true;
453+
} catch {
454+
return false;
455+
}
456+
};
457+
443458
return translateFn;
444459
}

‎packages/use-intl/src/core/createTranslator.tsx

+18
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,24 @@ export default function createTranslator<
125125
>(
126126
key: TargetKey
127127
): any;
128+
129+
// `has`
130+
has<
131+
TargetKey extends MessageKeys<
132+
NestedValueOf<
133+
{'!': IntlMessages},
134+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
135+
>,
136+
NestedKeyOf<
137+
NestedValueOf<
138+
{'!': IntlMessages},
139+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
140+
>
141+
>
142+
>
143+
>(
144+
key: TargetKey
145+
): boolean;
128146
} {
129147
// We have to wrap the actual function so the type inference for the optional
130148
// namespace works correctly. See https://stackoverflow.com/a/71529575/343045

‎packages/use-intl/src/react/useTranslations.test.tsx

+44-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
import {render, screen} from '@testing-library/react';
1+
import {render, renderHook, screen} from '@testing-library/react';
22
import {parseISO} from 'date-fns';
33
// eslint-disable-next-line import/no-named-as-default -- False positive
44
import IntlMessageFormat from 'intl-messageformat';
5-
import React, {ComponentProps, ReactNode} from 'react';
5+
import React, {ComponentProps, PropsWithChildren, ReactNode} from 'react';
66
import {it, expect, vi, describe, beforeEach} from 'vitest';
77
import {
88
Formats,
@@ -557,6 +557,48 @@ describe('t.raw', () => {
557557
});
558558
});
559559

560+
describe('t.has', () => {
561+
function wrapper({children}: PropsWithChildren) {
562+
return (
563+
<IntlProvider locale="en" messages={{foo: 'foo'}}>
564+
{children}
565+
</IntlProvider>
566+
);
567+
}
568+
569+
it('returns true for existing messages', () => {
570+
const {result: t} = renderHook(() => useTranslations(), {wrapper});
571+
expect(t.current.has('foo')).toBe(true);
572+
});
573+
574+
it('returns true for an empty message', () => {
575+
const {result: t} = renderHook(() => useTranslations(), {
576+
wrapper({children}: PropsWithChildren) {
577+
return (
578+
<IntlProvider locale="en" messages={{foo: ''}}>
579+
{children}
580+
</IntlProvider>
581+
);
582+
}
583+
});
584+
expect(t.current.has('foo')).toBe(true);
585+
});
586+
587+
it('returns false for missing messages', () => {
588+
const {result: t} = renderHook(() => useTranslations(), {wrapper});
589+
expect(t.current.has('bar')).toBe(false);
590+
});
591+
592+
it('returns false when no messages are provided', () => {
593+
const {result: t} = renderHook(() => useTranslations(), {
594+
wrapper({children}: PropsWithChildren) {
595+
return <IntlProvider locale="en">{children}</IntlProvider>;
596+
}
597+
});
598+
expect(t.current.has('foo')).toBe(false);
599+
});
600+
});
601+
560602
describe('error handling', () => {
561603
it('allows to configure a fallback', () => {
562604
const onError = vi.fn();

‎packages/use-intl/src/react/useTranslations.tsx

+18
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,24 @@ export default function useTranslations<
105105
>(
106106
key: TargetKey
107107
): any;
108+
109+
// `has`
110+
has<
111+
TargetKey extends MessageKeys<
112+
NestedValueOf<
113+
{'!': IntlMessages},
114+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
115+
>,
116+
NestedKeyOf<
117+
NestedValueOf<
118+
{'!': IntlMessages},
119+
[NestedKey] extends [never] ? '!' : `!.${NestedKey}`
120+
>
121+
>
122+
>
123+
>(
124+
key: TargetKey
125+
): boolean;
108126
} {
109127
const context = useIntlContext();
110128
const messages = context.messages as IntlMessages;

0 commit comments

Comments
 (0)