OpenAPI: Implement i18n

.changeset/clean-eagles-switch.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-openapi': minor
+---
+
+Implement i18n

.changeset/old-snails-yawn.md

@@ -0,0 +1,6 @@
+---
+'fumadocs-ui': minor
+'@fumadocs/base-ui': minor
+---
+
+Improved `defineI18nUI()` usage: allow language translations to be defined at root config.

apps/docs/content/docs/(framework)/integrations/openapi/api-page.mdx

@@ -98,6 +98,31 @@ paths:
             planter.list({ unwatered: true });
 ```
 
+### Internationalization
+
+Assuming you have configured [Internationalization](/docs/internationalization) at UI level:
+
+```tsx title="layout.shared.tsx"
+import { defineI18n } from 'fumadocs-core/i18n';
+import { defineI18nUI } from 'fumadocs-ui/i18n';
+import { defineI18nOpenAPI } from 'fumadocs-openapi/i18n';
+
+const i18n = defineI18n({
+  languages: ['en', 'cn'],
+  defaultLanguage: 'en',
+});
+
+export let i18nUI = defineI18nUI(i18n, {
+  cn: { displayName: 'Chinese' },
+});
+
+i18nUI = defineI18nOpenAPI(i18nUI, {
+  cn: {
+    titleRequestBody: '請求正文',
+  },
+});
+```
+
 ## Media Adapters
 
 You can create a media adapter to support other media types in API pages, a media adapter implements:

apps/docs/content/docs/(framework)/internationalization/next.mdx

@@ -45,16 +45,14 @@ import { i18n } from '@/lib/i18n';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
-// [!code ++:11]
+// [!code ++:9]
 export const i18nUI = defineI18nUI(i18n, {
-  translations: {
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
+  },
-    },
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    search: '搜尋文檔',
-      search: '搜尋文檔',
-    },
   },
 });
 
@@ -71,7 +69,6 @@ Pass translations to `<RootProvider />`:
 
 ```tsx title="app/[lang]/layout.tsx"
 import { RootProvider } from 'fumadocs-ui/provider/next';
-import { defineI18nUI } from 'fumadocs-ui/i18n';
 import { i18nUI } from '@/lib/layout.shared';
 
 export default async function RootLayout({

apps/docs/content/docs/(framework)/internationalization/react-router.mdx

@@ -70,16 +70,14 @@ import { i18n } from '@/lib/i18n';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
-// [!code ++:11]
+// [!code ++:9]
 export const i18nUI = defineI18nUI(i18n, {
-  translations: {
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
+  },
-    },
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    search: '搜尋文檔',
-      search: '搜尋文檔',
-    },
   },
 });
 

apps/docs/content/docs/(framework)/internationalization/tanstack-start.mdx

@@ -29,16 +29,14 @@ import { i18n } from '@/lib/i18n';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
-// [!code ++:11]
+// [!code ++:9]
 export const i18nUI = defineI18nUI(i18n, {
-  translations: {
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
+  },
-    },
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    search: '搜尋文檔',
-      search: '搜尋文檔',
-    },
   },
 });
 

examples/i18n/lib/layout.shared.tsx

@@ -3,20 +3,18 @@ import { i18n } from '@/lib/i18n';
 import { defineI18nUI } from 'fumadocs-ui/i18n';
 
 export const i18nUI = defineI18nUI(i18n, {
-  translations: {
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
+  },
-    },
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    toc: '目錄',
-      toc: '目錄',
+    search: '搜尋文檔',
-      search: '搜尋文檔',
+    lastUpdate: '最後更新於',
-      lastUpdate: '最後更新於',
+    searchNoResult: '沒有結果',
-      searchNoResult: '沒有結果',
+    previousPage: '上一頁',
-      previousPage: '上一頁',
+    nextPage: '下一頁',
-      nextPage: '下一頁',
+    chooseLanguage: '選擇語言',
-      chooseLanguage: '選擇語言',
-    },
   },
 });
 

examples/tanstack-start-i18n/src/routes/__root.tsx

@@ -33,14 +33,12 @@ function RootComponent() {
 }
 
 const { provider } = defineI18nUI(i18n, {
-  translations: {
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    search: 'Translated Content',
-      search: 'Translated Content',
+  },
-    },
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
-    },
   },
 });
 

examples/waku-i18n/src/components/provider.tsx

@@ -6,14 +6,12 @@ import { i18n } from '@/lib/i18n';
 import { useRouter } from 'waku/router/client';
 
 const { provider } = defineI18nUI(i18n, {
-  translations: {
+  en: {
-    en: {
+    displayName: 'English',
-      displayName: 'English',
+  },
-    },
+  cn: {
-    cn: {
+    displayName: 'Chinese',
-      displayName: 'Chinese',
+    search: 'Search (Translated)',
-      search: 'Search (Translated)',
-    },
   },
 });
 

packages/base-ui/src/contexts/i18n.tsx

@@ -17,15 +17,19 @@ export interface Translations {
   editOnGithub: string;
 }
 
-export interface LocaleItem {
+export type TranslationsOption = {
+  [key: string]: string | TranslationsOption;
+};
+
+interface LocaleItem {
   name: string;
   locale: string;
 }
 
 interface I18nContextType {
+  text: Translations & TranslationsOption;
   locale?: string;
   onChange?: (v: string) => void;
-  text: Translations;
   locales?: LocaleItem[];
 }
 
@@ -43,12 +47,11 @@ export const defaultTranslations: Translations = {
 };
 
 const I18nContext = createContext<I18nContextType>({
-  text: defaultTranslations,
+  text: { ...defaultTranslations },
 });
 
 export function I18nLabel(props: { label: keyof Translations }): string {
-  const { text } = useI18n();
+  const text = useI18n().text;
-
   return text[props.label];
 }
 
@@ -60,7 +63,7 @@ export interface I18nProviderProps {
   /**
    * Current locale
    */
-  locale: string;
+  locale?: string;
 
   /**
    * Handle changes to the locale, redirect user when not specified.
@@ -70,7 +73,7 @@ export interface I18nProviderProps {
   /**
    * Translations of current locale
    */
-  translations?: Partial<Translations>;
+  translations?: TranslationsOption;
 
   /**
    * Available languages

packages/base-ui/src/i18n.tsx

@@ -7,18 +7,25 @@ export interface I18nUIConfig<Languages extends string> extends I18nConfig<Langu
   /**
    * get i18n config for Fumadocs UI `<RootProvider i18n={config} />`.
    */
-  provider: (locale?: string) => I18nProviderProps;
+  provider: (locale?: Languages | (string & {})) => I18nProviderProps;
 }
 
+type TranslationsConfig<Languages extends string> = {
+  [K in Languages]?: Partial<Translations> & { displayName?: string };
+};
+
 export function defineI18nUI<Languages extends string>(
   config: I18nConfig<Languages>,
-  options: {
+  options:
-    translations: {
+    | {
-      [K in Languages]?: Partial<Translations> & { displayName?: string };
+        /**
-    };
+         * @deprecated you can directly define the translations in outer scope (the parent object of `translations`)
-  },
+         */
+        translations: TranslationsConfig<Languages>;
+      }
+    | TranslationsConfig<Languages> = {},
 ): I18nUIConfig<Languages> {
-  const { translations } = options;
+  const translations = 'translations' in options ? options.translations : options;
 
   return {
     ...config,

packages/openapi/package.json

@@ -20,6 +20,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./i18n": "./dist/i18n.js",
     "./playground": "./dist/playground/index.js",
     "./playground/client": "./dist/playground/client.js",
     "./requests/generators": "./dist/requests/generators/index.js",
@@ -49,6 +50,7 @@
     "types:check": "tsc --noEmit"
   },
   "dependencies": {
+    "@fastify/deepmerge": "^3.2.1",
     "@fumari/json-schema-ts": "^0.0.2",
     "@fumari/stf": "workspace:*",
     "@radix-ui/react-accordion": "^1.2.12",

packages/openapi/src/i18n.ts

@@ -0,0 +1,143 @@
+import type { I18nUIConfig } from 'fumadocs-ui/i18n';
+import { deepmerge } from '@fastify/deepmerge';
+import type { TranslationsOption } from 'fumadocs-ui/contexts/i18n';
+
+export const defaultTranslations = {
+  // General
+  loading: 'loading...',
+  empty: 'Empty',
+  copy: 'Copy',
+  send: 'Send',
+  authorization: 'Authorization',
+  cookies: 'Cookies',
+  query: 'Query',
+  path: 'Path',
+  header: 'Header',
+  body: 'Body',
+  deprecated: 'Deprecated',
+  submit: 'Submit',
+  unsupported: 'Unsupported',
+  close: 'Close',
+  inputPlaceholder: 'Enter value',
+
+  // Request tabs
+  titleRequestTabs: 'Example Requests',
+  requestTabNameDefault: 'Default',
+  queryParameters: 'Query Parameters',
+  pathParameters: 'Path Parameters',
+  headerParameters: 'Header Parameters',
+  cookieParameters: 'Cookie Parameters',
+
+  // Operation sections
+  titleRequestBody: 'Request Body',
+  titleResponseBody: 'Response Body',
+  titleCallbacks: 'Callbacks',
+
+  // Auth scheme
+  authBasicTokenExample: 'Basic <token>',
+  authBearerTokenExample: 'Bearer <token>',
+  openIdConnect: 'OpenID Connect',
+  authTokenIn: 'In',
+  authScope: 'Scope',
+
+  // TypeScript panel
+  typeScriptDefinitions: 'TypeScript Definitions',
+  useTypeInTypeScript: 'Use the {name} type in TypeScript.',
+
+  // Schema info tags
+  schemaDefault: 'Default',
+  schemaMatch: 'Match',
+  schemaFormat: 'Format',
+  schemaMultipleOf: 'Multiple Of',
+  schemaRange: 'Range',
+  schemaLength: 'Length',
+  schemaProperties: 'Properties',
+  schemaItems: 'Items',
+  schemaValueIn: 'Value in',
+  schemaExample: 'Example',
+
+  // Response tabs
+  responseTabName: 'Example {key}',
+  responseTabNameDefault: 'Example',
+
+  // Playground
+  closeJsonEditor: 'Close JSON Editor',
+  openJsonEditor: 'Open JSON Editor',
+  accessToken: 'Access Token',
+  authorize: 'Authorize',
+  openIdUnsupported:
+    'OpenID Connect is not supported at the moment, you can still set an access token here.',
+
+  // Status info
+  statusBadRequest: 'Bad Request',
+  statusUnauthorized: 'Unauthorized',
+  statusForbidden: 'Forbidden',
+  statusNotFound: 'Not Found',
+  statusInternalServerError: 'Internal Server Error',
+  statusSuccessful: 'Successful',
+  statusError: 'Error',
+  statusNoDescription: 'No Description',
+
+  // OAuth dialog
+  obtainAccessToken: 'Obtain the access token for API.',
+  resourceOwnerPassword: 'Resource Owner Password Flow',
+  resourceOwnerPasswordDesc: 'Authenticate using username and password.',
+  clientCredentials: 'Client Credentials',
+  clientCredentialsDesc: 'Intended for the server-to-server authentication.',
+  authorizationCode: 'Authorization code',
+  authorizationCodeDesc: 'Authenticate with 3rd party services',
+  implicit: 'Implicit',
+  implicitDesc: 'Retrieve the access token directly.',
+  deviceAuthorization: 'Device Authorization',
+  deviceAuthorizationDesc: 'Authenticate with device.',
+  clientId: 'Client ID',
+  clientIdHint: 'The client ID of your OAuth application.',
+  clientSecret: 'Client Secret',
+  clientSecretHint: 'The client secret of your OAuth application.',
+  usernameField: 'Username',
+  passwordField: 'Password',
+  fetchingToken: 'Fetching token...',
+
+  // Server select
+  serverUrl: 'Server URL',
+  serverUrlDescription: 'The base URL of your API endpoint.',
+  serverUrlFieldPlaceholder: 'Enter Value',
+
+  // Schema UI
+  schemaShowArray: 'Array Item',
+  schemaHideArray: 'Array Item',
+  schemaFilterPropertiesPlaceholder: 'Filter Properties',
+  schemaFilterPropertiesEmpty: 'No property matching',
+
+  // Inputs (playground)
+  playgroundShowProperty: 'Show Property',
+  playgroundPropertyPlaceholder: 'Enter Property Name',
+  playgroundNewProperty: 'New',
+  playgroundNewItem: 'New Item',
+  playgroundRemoveItem: 'Remove Item',
+  playgroundSelectPlaceholder: 'Select',
+  playgroundSelected: 'Selected',
+  playgroundInputUpload: 'Upload',
+  playgroundInputUnset: 'Unset',
+};
+
+export type Translations = typeof defaultTranslations;
+
+export function defineI18nOpenAPI<Languages extends string>(
+  config: I18nUIConfig<Languages>,
+  translations: Partial<Record<NoInfer<Languages>, Partial<Translations>>>,
+): I18nUIConfig<Languages> {
+  const dm = deepmerge();
+  return {
+    ...config,
+    provider(locale = config.defaultLanguage) {
+      const out = config.provider(locale);
+      const data = translations[locale as Languages];
+      if (data) {
+        out.translations ??= {};
+        out.translations.openapi = dm(defaultTranslations, data) as TranslationsOption;
+      }
+      return out;
+    },
+  };
+}

packages/openapi/src/playground/client.tsx

@@ -52,6 +52,7 @@ import { objectGet, objectSet, stringifyFieldKey } from '@fumari/stf/lib/utils';
 import { FieldInput, FieldSet, JsonInput, ObjectInput } from './components/inputs';
 import type { ParameterObject } from '@/types';
 import { ClientCodeBlock } from '@/ui/components/codeblock';
+import { useTranslations } from '@/ui/client/i18n';
 
 export interface FormValues extends Record<string, unknown> {
   path: Record<string, unknown>;
@@ -139,6 +140,7 @@ export default function PlaygroundClient({
   readOnly,
   ...rest
 }: PlaygroundClientProps) {
+  const t = useTranslations();
   const { example: exampleId, examples, setExampleData } = useExampleRequests();
   const storageKeys = useStorageKey();
   const {
@@ -268,7 +270,7 @@ export default function PlaygroundClient({
               className={cn(buttonVariants({ color: 'primary', size: 'sm' }), 'w-14 py-1.5')}
               disabled={testQuery.isLoading}
             >
-              {testQuery.isLoading ? <LoaderCircle className="size-4 animate-spin" /> : 'Send'}
+              {testQuery.isLoading ? <LoaderCircle className="size-4 animate-spin" /> : t.send}
             </button>
           </div>
           {testQuery.data ? <ResultDisplay data={testQuery.data} reset={testQuery.reset} /> : null}
@@ -304,9 +306,10 @@ function SecurityTabs({
 }) {
   const [open, setOpen] = useState(false);
   const engine = useDataEngine();
+  const t = useTranslations();
 
   const result = (
-    <CollapsiblePanel title="Authorization">
+    <CollapsiblePanel title={t.authorization}>
       <Select value={securityId.toString()} onValueChange={(v) => setSecurityId(Number(v))}>
         <SelectTrigger>
           <SelectValue />
@@ -367,6 +370,7 @@ const ParamTypes = ['path', 'header', 'cookie', 'query'] as const;
 
 function FormBody({ parameters = [], body }: Pick<PlaygroundClientProps, 'parameters' | 'body'>) {
   const { renderParameterField, renderBodyField } = useApiContext().client.playground ?? {};
+  const t = useTranslations();
   const panels = useMemo(() => {
     return ParamTypes.map((type) => {
       const items = parameters.filter((v) => v.in === type);
@@ -377,10 +381,10 @@ function FormBody({ parameters = [], body }: Pick<PlaygroundClientProps, 'parame
           key={type}
           title={
             {
-              header: 'Header',
+              header: t.header,
-              cookie: 'Cookies',
+              cookie: t.cookies,
-              query: 'Query',
+              query: t.query,
-              path: 'Path',
+              path: t.path,
             }[type]
           }
         >
@@ -410,13 +414,13 @@ function FormBody({ parameters = [], body }: Pick<PlaygroundClientProps, 'parame
         </CollapsiblePanel>
       );
     });
-  }, [parameters, renderParameterField]);
+  }, [parameters, renderParameterField, t]);
 
   return (
     <>
       {panels}
       {body && (
-        <CollapsiblePanel title="Body">
+        <CollapsiblePanel title={t.body}>
           {renderBodyField ? renderBodyField('body', body) : <BodyInput field={body.schema} />}
         </CollapsiblePanel>
       )}
@@ -427,6 +431,7 @@ function FormBody({ parameters = [], body }: Pick<PlaygroundClientProps, 'parame
 function BodyInput({ field: _field }: { field: ParsedSchema }) {
   const field = useResolvedSchema(_field);
   const [isJson, setIsJson] = useState(false);
+  const t = useTranslations();
 
   if (field.format === 'binary') return <FieldSet field={field} fieldName={['body']} isRequired />;
 
@@ -444,7 +449,7 @@ function BodyInput({ field: _field }: { field: ParsedSchema }) {
           onClick={() => setIsJson(false)}
           type="button"
         >
-          Close JSON Editor
+          {t.closeJsonEditor}
         </button>
         <JsonInput fieldName={['body']} />
       </>
@@ -468,7 +473,7 @@ function BodyInput({ field: _field }: { field: ParsedSchema }) {
           )}
           onClick={() => setIsJson(true)}
         >
-          Open JSON Editor
+          {t.openJsonEditor}
         </button>
       }
     />
@@ -490,6 +495,7 @@ function useAuthInputs(
   transform?: (fields: AuthField[]) => AuthField[],
 ) {
   const storageKeys = useStorageKey();
+  const t = useTranslations();
   const inputs = useMemo(() => {
     const result: AuthField[] = [];
     if (!securities) return result;
@@ -540,7 +546,7 @@ function useAuthInputs(
           children: (
             <fieldset className="flex flex-col gap-2">
               <label htmlFor={stringifyFieldKey(fieldName)} className={cn(labelVariants())}>
-                Access Token
+                {t.accessToken}
               </label>
               <div className="flex gap-2">
                 <FieldInput
@@ -561,7 +567,7 @@ function useAuthInputs(
                     }),
                   )}
                 >
-                  Authorize
+                  {t.authorize}
                 </OauthDialogTrigger>
               </div>
             </fieldset>
@@ -576,7 +582,7 @@ function useAuthInputs(
           defaultValue: 'Bearer ',
           children: (
             <FieldSet
-              name="Authorization (header)"
+              name={`${t.authorization} (${t.header})`}
               fieldName={fieldName}
               isRequired
               field={{
@@ -613,17 +619,14 @@ function useAuthInputs(
           children: (
             <>
               <FieldSet
-                name="Authorization (header)"
+                name={`${t.authorization} (${t.header})`}
                 isRequired
                 fieldName={fieldName}
                 field={{
                   type: 'string',
                 }}
               />
-              <p className="text-fd-muted-foreground text-xs">
+              <p className="text-fd-muted-foreground text-xs">{t.openIdUnsupported}</p>
-                OpenID Connect is not supported at the moment, you can still set an access token
-                here.
-              </p>
             </>
           ),
         });
@@ -631,7 +634,7 @@ function useAuthInputs(
     }
 
     return transform ? transform(result) : result;
-  }, [securities, transform]);
+  }, [securities, transform, t]);
 
   const mapInputs = (values: FormValues) => {
     const cloned = structuredClone(values);
@@ -695,7 +698,8 @@ function Route({ route, ...props }: ComponentProps<'div'> & { route: string }) {
 }
 
 function DefaultResultDisplay({ data, reset }: { data: FetchResult; reset: () => void }) {
-  const statusInfo = useMemo(() => getStatusInfo(data.status), [data.status]);
+  const t = useTranslations();
+  const statusInfo = useMemo(() => getStatusInfo(data.status, t), [data.status, t]);
 
   return (
     <div className="flex flex-col gap-3 mt-2 px-3 py-2 border-y bg-fd-secondary text-fd-secondary-foreground">
@@ -709,7 +713,7 @@ function DefaultResultDisplay({ data, reset }: { data: FetchResult; reset: () =>
           className={cn(buttonVariants({ size: 'sm', variant: 'outline' }))}
           onClick={() => reset()}
         >
-          Close
+          {t.close}
         </button>
       </div>
       <p className="text-sm text-fd-muted-foreground">{data.status}</p>

packages/openapi/src/playground/components/inputs.tsx

@@ -23,6 +23,7 @@ import {
 import type { ParsedSchema } from '@/utils/schema';
 import { stringifyFieldKey } from '@fumari/stf/lib/utils';
 import { cva } from 'class-variance-authority';
+import { useTranslations } from '@/ui/client/i18n';
 
 const fieldLabelVariants = cva('w-full inline-flex items-center gap-0.5');
 
@@ -62,6 +63,7 @@ export function ObjectInput({
   });
 
   const hiddenProperties = isLazy ? schemaPropKeys.filter((key) => !_objectKeys.includes(key)) : [];
+  const t = useTranslations();
 
   return (
     <div
@@ -74,7 +76,7 @@ export function ObjectInput({
       {isLazy && hiddenProperties.length > 0 && (
         <Select value="" onValueChange={onAppend}>
           <SelectTrigger className="col-span-full">
-            <SelectValue placeholder="Show Property" />
+            <SelectValue placeholder={t.playgroundShowProperty} />
           </SelectTrigger>
           <SelectContent>
             {hiddenProperties.map((key) => (
@@ -92,7 +94,7 @@ export function ObjectInput({
           toolbar = (
             <button
               type="button"
-              aria-label="Remove Item"
+              aria-label={t.playgroundRemoveItem}
               className={cn(
                 buttonVariants({
                   color: 'outline',
@@ -123,7 +125,7 @@ export function ObjectInput({
         <div className="flex gap-2 order-last col-span-full">
           <Input
             value={nextName}
-            placeholder="Enter Property Name"
+            placeholder={t.playgroundPropertyPlaceholder}
             onChange={(e) => setNextName(e.target.value)}
             onKeyDown={(e) => {
               if (e.key === 'Enter') {
@@ -141,7 +143,7 @@ export function ObjectInput({
               setNextName('');
             }}
           >
-            New
+            {t.playgroundNewProperty}
           </button>
         </div>
       )}
@@ -186,6 +188,7 @@ export function FieldInput({
 }) {
   const [value, setValue] = useFieldValue(fieldName);
   const id = stringifyFieldKey(fieldName);
+  const t = useTranslations();
   if (field.type === 'null') return;
 
   if (field.type === 'string' && field.format === 'binary') {
@@ -202,11 +205,11 @@ export function FieldInput({
         >
           {value instanceof File ? (
             <>
-              <span className="text-fd-muted-foreground text-xs">Selected</span>
+              <span className="text-fd-muted-foreground text-xs">{t.playgroundSelected}</span>
               <span className="truncate w-0 flex-1 text-end">{value.name}</span>
             </>
           ) : (
-            <span className="text-fd-muted-foreground">Upload</span>
+            <span className="text-fd-muted-foreground">{t.playgroundInputUpload}</span>
           )}
         </label>
         <input
@@ -232,7 +235,7 @@ export function FieldInput({
         onValueChange={(v) => setValue(field.enum![Number(v)])}
       >
         <SelectTrigger id={id} {...props}>
-          <SelectValue placeholder="Select" />
+          <SelectValue placeholder={t.playgroundSelectPlaceholder} />
         </SelectTrigger>
         <SelectContent>
           {field.enum.map((item, i) => (
@@ -240,7 +243,7 @@ export function FieldInput({
               {typeof item === 'string' ? item : JSON.stringify(item, null, 2)}
             </SelectItem>
           ))}
-          {!isRequired && <SelectItem value="-1">Unset</SelectItem>}
+          {!isRequired && <SelectItem value="-1">{t.playgroundInputUnset}</SelectItem>}
         </SelectContent>
       </Select>
     );
@@ -258,7 +261,7 @@ export function FieldInput({
         <SelectContent>
           <SelectItem value="true">True</SelectItem>
           <SelectItem value="false">False</SelectItem>
-          {!isRequired && <SelectItem value="undefined">Unset</SelectItem>}
+          {!isRequired && <SelectItem value="undefined">{t.playgroundInputUnset}</SelectItem>}
         </SelectContent>
       </Select>
     );
@@ -268,7 +271,7 @@ export function FieldInput({
   return (
     <Input
       id={id}
-      placeholder="Enter value"
+      placeholder={t.inputPlaceholder}
       type={isNumber ? 'number' : 'text'}
       step={field.type === 'integer' ? 1 : undefined}
       value={String(value ?? '')}
@@ -521,6 +524,7 @@ function ArrayInput({
   const name = fieldName.at(-1) ?? '';
   const { generateDefault } = useSchemaUtils();
   const { items, insertItem, removeItem } = useArray(fieldName);
+  const t = useTranslations();
 
   return (
     <div {...props} className={cn('flex flex-col gap-2', props.className)}>
@@ -538,7 +542,7 @@ function ArrayInput({
           toolbar={
             <button
               type="button"
-              aria-label="Remove Item"
+              aria-label={t.playgroundRemoveItem}
               className={cn(
                 buttonVariants({
                   color: 'outline',
@@ -566,7 +570,7 @@ function ArrayInput({
         }}
       >
         <Plus className="size-4" />
-        New Item
+        {t.playgroundNewItem}
       </button>
     </div>
   );

packages/openapi/src/playground/components/oauth-dialog.tsx

@@ -9,7 +9,7 @@ import {
 import { useForm } from 'react-hook-form';
 import { Input, labelVariants } from '@/ui/components/input';
 import { useQuery } from '@/utils/use-query';
-import { type ReactNode, useEffect, useState } from 'react';
+import { type ReactNode, useEffect, useMemo, useState } from 'react';
 import { cn } from '@/utils/cn';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
 import {
@@ -20,6 +20,7 @@ import {
   SelectValue,
 } from '@/ui/components/select';
 import type { OAuth2SecurityScheme } from '@/types';
+import { useTranslations } from '@/ui/client/i18n';
 
 type FlowType = keyof NonNullable<OAuth2SecurityScheme['flows']>;
 
@@ -51,33 +52,11 @@ interface ImplicitState {
   client_id: string;
 }
 
-const FlowTypes = {
+interface FlowInfo {
-  password: {
+  name: ReactNode;
-    name: 'Resource Owner Password Flow',
+  description: ReactNode;
-    description: 'Authenticate using username and password.',
+  supported: boolean;
-    supported: true,
+}
-  },
-  clientCredentials: {
-    name: 'Client Credentials',
-    description: 'Intended for the server-to-server authentication.',
-    supported: true,
-  },
-  authorizationCode: {
-    name: 'Authorization code',
-    description: 'Authenticate with 3rd party services',
-    supported: true,
-  },
-  implicit: {
-    name: 'Implicit',
-    description: 'Retrieve the access token directly.',
-    supported: true,
-  },
-  deviceAuthorization: {
-    name: 'Device Authorization',
-    description: 'Authenticate with device.',
-    supported: false,
-  },
-} as const;
 
 export function OauthDialog({
   scheme,
@@ -90,7 +69,38 @@ export function OauthDialog({
   const [type, setType] = useState(() => {
     return Object.keys(scheme.flows!)[0] as FlowType;
   });
-  const { supported } = FlowTypes[type];
+  const t = useTranslations();
+  const allFlows: Record<FlowType, FlowInfo> = useMemo(
+    () => ({
+      password: {
+        name: t.resourceOwnerPassword,
+        description: t.resourceOwnerPasswordDesc,
+        supported: true,
+      },
+      clientCredentials: {
+        name: t.clientCredentials,
+        description: t.clientCredentialsDesc,
+        supported: true,
+      },
+      authorizationCode: {
+        name: t.authorizationCode,
+        description: t.authorizationCodeDesc,
+        supported: true,
+      },
+      implicit: {
+        name: t.implicit,
+        description: t.implicitDesc,
+        supported: true,
+      },
+      deviceAuthorization: {
+        name: t.deviceAuthorization,
+        description: t.deviceAuthorizationDesc,
+        supported: false,
+      },
+    }),
+    [t],
+  );
+
   const form = useForm<FormValues>({
     defaultValues: {
       clientId: '',
@@ -264,8 +274,8 @@ export function OauthDialog({
       {children}
       <DialogContent>
         <DialogHeader>
-          <DialogTitle>Authorization</DialogTitle>
+          <DialogTitle>{t.authorization}</DialogTitle>
-          <DialogDescription>Obtain the access token for API.</DialogDescription>
+          <DialogDescription>{t.obtainAccessToken}</DialogDescription>
         </DialogHeader>
         <form
           className="flex flex-col gap-6"
@@ -280,7 +290,7 @@ export function OauthDialog({
             </SelectTrigger>
             <SelectContent>
               {Object.keys(scheme.flows!).map((key) => {
-                const { name, description } = FlowTypes[key as FlowType];
+                const { name, description } = allFlows[key as FlowType];
 
                 return (
                   <SelectItem key={key} value={key}>
@@ -297,14 +307,12 @@ export function OauthDialog({
             type === 'implicit') && (
             <fieldset className="flex flex-col gap-1.5">
               <label htmlFor="client_id" className={cn(labelVariants())}>
-                Client ID
+                {t.clientId}
               </label>
-              <p className="text-fd-muted-foreground text-sm">
+              <p className="text-fd-muted-foreground text-sm">{t.clientIdHint}</p>
-                The client ID of your OAuth application.
-              </p>
               <Input
                 id="client_id"
-                placeholder="Enter value"
+                placeholder={t.inputPlaceholder}
                 type="text"
                 autoComplete="off"
                 disabled={isLoading}
@@ -315,14 +323,12 @@ export function OauthDialog({
           {(type === 'authorizationCode' || type === 'clientCredentials') && (
             <fieldset className="flex flex-col gap-1.5">
               <label htmlFor="client_secret" className={cn(labelVariants())}>
-                Client Secret
+                {t.clientSecret}
               </label>
-              <p className="text-fd-muted-foreground text-sm">
+              <p className="text-fd-muted-foreground text-sm">{t.clientSecretHint}</p>
-                The client secret of your OAuth application.
-              </p>
               <Input
                 id="client_secret"
-                placeholder="Enter value"
+                placeholder={t.inputPlaceholder}
                 type="password"
                 autoComplete="off"
                 disabled={isLoading}
@@ -334,11 +340,11 @@ export function OauthDialog({
             <>
               <fieldset className="flex flex-col gap-1.5">
                 <label htmlFor="username" className={cn(labelVariants())}>
-                  Username
+                  {t.usernameField}
                 </label>
                 <Input
                   id="username"
-                  placeholder="Enter value"
+                  placeholder={t.inputPlaceholder}
                   type="text"
                   disabled={isLoading}
                   autoComplete="off"
@@ -347,11 +353,11 @@ export function OauthDialog({
               </fieldset>
               <fieldset className="flex flex-col gap-1.5">
                 <label htmlFor="password" className={cn(labelVariants())}>
-                  Client Secret
+                  {t.clientSecret}
                 </label>
                 <Input
                   id="password"
-                  placeholder="Enter value"
+                  placeholder={t.inputPlaceholder}
                   type="password"
                   autoComplete="off"
                   disabled={isLoading}
@@ -360,7 +366,7 @@ export function OauthDialog({
               </fieldset>
             </>
           )}
-          {supported ? (
+          {allFlows[type].supported ? (
             <>
               {error ? <p className="text-red-400 font-medium text-sm">{String(error)}</p> : null}
               <button
@@ -372,12 +378,12 @@ export function OauthDialog({
                   }),
                 )}
               >
-                {authCodeCallback.isLoading ? 'Fetching token...' : 'Submit'}
+                {authCodeCallback.isLoading ? t.fetchingToken : t.submit}
               </button>
             </>
           ) : (
             <p className="text-fd-muted-foreground bg-fd-muted p-2 rounded-lg border">
-              Unsupported
+              {t.unsupported}
             </p>
           )}
         </form>

packages/openapi/src/playground/components/server-select.tsx

@@ -23,12 +23,14 @@ import type { ServerVariableObject } from '@/types';
 import type { NoReference } from '@/utils/schema';
 import { StfProvider, useFieldValue, useListener, useStf } from '@fumari/stf';
 import { EditIcon } from 'lucide-react';
+import { useTranslations } from '@/ui/client/i18n';
 
 export default function ServerSelect(props: ComponentProps<typeof DialogTrigger>) {
   const { servers } = useServerContext();
   const { server, setServer, setServerVariables } = useServerSelectContext();
   const [open, setOpen] = useState(false);
   const [isMounted, setIsMounted] = useState(false);
+  const t = useTranslations();
 
   useEffect(() => {
     setIsMounted(true);
@@ -47,7 +49,7 @@ export default function ServerSelect(props: ComponentProps<typeof DialogTrigger>
         )}
       >
         <span className="px-2 py-0.5 -ms-2 font-medium rounded-lg border bg-fd-secondary text-fd-secondary-foreground shadow-sm">
-          {server?.name ?? 'Server URL'}
+          {server?.name ?? t.serverUrl}
         </span>
         <code className="truncate min-w-0 flex-1">
           {isMounted
@@ -55,14 +57,14 @@ export default function ServerSelect(props: ComponentProps<typeof DialogTrigger>
                 server ? resolveServerUrl(server.url, server.variables) : '/',
                 window.location.origin,
               )
-            : 'loading...'}
+            : t.loading}
         </code>
         <EditIcon className="size-4" />
       </DialogTrigger>
       <DialogContent>
         <DialogHeader>
-          <DialogTitle>Server URL</DialogTitle>
+          <DialogTitle>{t.serverUrl}</DialogTitle>
-          <DialogDescription>The base URL of your API endpoint.</DialogDescription>
+          <DialogDescription>{t.serverUrlDescription}</DialogDescription>
         </DialogHeader>
         <Select value={server?.url} onValueChange={setServer}>
           <SelectTrigger>
@@ -143,6 +145,7 @@ function Field({
   variable: NoReference<ServerVariableObject>;
   fieldName: string;
 }) {
+  const t = useTranslations();
   const [value, setValue] = useFieldValue([fieldName], {
     compute(currentValue) {
       return typeof currentValue === 'string' ? currentValue : undefined;
@@ -171,7 +174,7 @@ function Field({
       id={fieldName}
       value={value}
       onChange={(e) => setValue(e.target.value)}
-      placeholder="Enter Value"
+      placeholder={t.serverUrlFieldPlaceholder}
     />
   );
 }

packages/openapi/src/playground/status-info.tsx

@@ -1,4 +1,5 @@
 import { CircleCheck, CircleX } from 'lucide-react';
+import type { Translations } from '@/i18n';
 
 interface StatusInfo {
   description: string;
@@ -6,45 +7,37 @@ interface StatusInfo {
   icon: React.ElementType;
 }
 
-const statusMap: Record<number, StatusInfo> = {
+const statusKeys: Record<
-  400: { description: 'Bad Request', color: 'text-red-500', icon: CircleX },
+  number,
-  401: {
+  { key: keyof Translations; color: string; icon: React.ElementType }
-    description: 'Unauthorized',
+> = {
-    color: 'text-red-500',
+  400: { key: 'statusBadRequest', color: 'text-red-500', icon: CircleX },
-    icon: CircleX,
+  401: { key: 'statusUnauthorized', color: 'text-red-500', icon: CircleX },
-  },
+  403: { key: 'statusForbidden', color: 'text-red-500', icon: CircleX },
-  403: { description: 'Forbidden', color: 'text-red-500', icon: CircleX },
+  404: { key: 'statusNotFound', color: 'text-fd-muted-foreground', icon: CircleX },
-  404: {
+  500: { key: 'statusInternalServerError', color: 'text-red-500', icon: CircleX },
-    description: 'Not Found',
-    color: 'text-fd-muted-foreground',
-    icon: CircleX,
-  },
-  500: {
-    description: 'Internal Server Error',
-    color: 'text-red-500',
-    icon: CircleX,
-  },
 };
 
-export function getStatusInfo(status: number): StatusInfo {
+export function getStatusInfo(status: number, t: Translations): StatusInfo {
-  if (status in statusMap) {
+  if (status in statusKeys) {
-    return statusMap[status];
+    const { key, color, icon } = statusKeys[status];
+    return { description: t[key], color, icon };
   }
 
   if (status >= 200 && status < 300) {
     return {
-      description: 'Successful',
+      description: t.statusSuccessful,
       color: 'text-green-500',
       icon: CircleCheck,
     };
   }
 
   if (status >= 400) {
-    return { description: 'Error', color: 'text-red-500', icon: CircleX };
+    return { description: t.statusError, color: 'text-red-500', icon: CircleX };
   }
 
   return {
-    description: 'No Description',
+    description: t.statusNoDescription,
     color: 'text-fd-muted-foreground',
     icon: CircleX,
   };

packages/openapi/src/types.ts

@@ -52,8 +52,8 @@ export interface RenderContext
 
   renderHeading: (
     depth: number,
-    text: string,
+    text: string | ReactNode,
-    props?: HTMLAttributes<HTMLHeadingElement>,
+    props?: HTMLAttributes<HTMLHeadingElement> & { id?: string },
   ) => ReactNode;
   renderCodeBlock: (lang: string, code: string) => ReactNode;
 }

packages/openapi/src/ui/base.tsx

@@ -259,7 +259,8 @@ export function createAPIPage(
       },
       slugger,
       async renderHeading(depth, text, props) {
-        const id = slugger.slug(text);
+        const id = typeof text === 'string' ? slugger.slug(text) : props?.id;
+        if (!id) throw new Error("missing 'id' for non-string children");
 
         if (options.renderHeading) {
           return options.renderHeading({ id, children: text, ...props }, depth);

packages/openapi/src/ui/client/i18n.ts

@@ -0,0 +1,25 @@
+'use client';
+import { defaultTranslations, type Translations } from '@/i18n';
+import { useI18n } from 'fumadocs-ui/contexts/i18n';
+
+export function useTranslations(): Translations {
+  return (useI18n().text.openapi ?? defaultTranslations) as unknown as Translations;
+}
+
+export interface OpenAPII18nLabelProps {
+  label: keyof Translations;
+  /** Replace {key} placeholders in the translation string */
+  replacements?: Record<string, string>;
+}
+
+/**
+ * Renders a translated string. Use in server components so the label is resolved on the client from the current locale.
+ */
+export function I18nLabel({ label, replacements = {} }: OpenAPII18nLabelProps): string {
+  const text = useTranslations();
+  let value = text[label];
+  for (const [k, v] of Object.entries(replacements)) {
+    value = value.replaceAll(`{${k}}`, v);
+  }
+  return value;
+}

packages/openapi/src/ui/components/dialog.tsx

@@ -5,6 +5,7 @@ import * as DialogPrimitive from '@radix-ui/react-dialog';
 import { X } from 'lucide-react';
 import { cn } from '@/utils/cn';
 import { buttonVariants } from 'fumadocs-ui/components/ui/button';
+import { useTranslations } from '@/ui/client/i18n';
 
 const Dialog = DialogPrimitive.Root;
 
@@ -32,30 +33,33 @@ DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
 const DialogContent = React.forwardRef<
   React.ComponentRef<typeof DialogPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
->(({ className, children, ...props }, ref) => (
+>(({ className, children, ...props }, ref) => {
-  <DialogPortal>
+  const t = useTranslations();
-    <DialogOverlay />
+  return (
-    <DialogPrimitive.Content
+    <DialogPortal>
-      ref={ref}
+      <DialogOverlay />
-      className={cn(
+      <DialogPrimitive.Content
-        'fixed left-1/2 top-1/2 z-50 flex flex-col gap-4 w-full max-w-lg -translate-x-1/2 -translate-y-1/2 border bg-fd-popover p-4 shadow-lg rounded-xl duration-200 data-[state=open]:animate-fd-dialog-in data-[state=closed]:animate-fd-dialog-out focus-visible:outline-none',
+        ref={ref}
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      <DialogPrimitive.Close
-        aria-label="Close"
         className={cn(
-          buttonVariants({ size: 'icon-sm', color: 'ghost' }),
+          'fixed left-1/2 top-1/2 z-50 flex flex-col gap-4 w-full max-w-lg -translate-x-1/2 -translate-y-1/2 border bg-fd-popover p-4 shadow-lg rounded-xl duration-200 data-[state=open]:animate-fd-dialog-in data-[state=closed]:animate-fd-dialog-out focus-visible:outline-none',
-          'absolute end-2 top-2 text-fd-muted-foreground/70',
+          className,
         )}
+        {...props}
       >
-        <X />
+        {children}
-      </DialogPrimitive.Close>
+        <DialogPrimitive.Close
-    </DialogPrimitive.Content>
+          aria-label={t.close}
-  </DialogPortal>
+          className={cn(
-));
+            buttonVariants({ size: 'icon-sm', color: 'ghost' }),
+            'absolute end-2 top-2 text-fd-muted-foreground/70',
+          )}
+        >
+          <X />
+        </DialogPrimitive.Close>
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  );
+});
 DialogContent.displayName = DialogPrimitive.Content.displayName;
 
 const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (

packages/openapi/src/ui/operation/client.tsx

@@ -12,6 +12,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/ui/components/select';
+import { useTranslations } from '@/ui/client/i18n';
 
 export function CopyTypeScriptPanel({
   name,
@@ -25,6 +26,8 @@ export function CopyTypeScriptPanel({
   const [isChecked, onCopy] = useCopyButton(() => {
     void navigator.clipboard.writeText(code);
   });
+  const t = useTranslations();
+  const useTypeText = t.useTypeInTypeScript.replace('{name}', name);
 
   return (
     <div
@@ -34,8 +37,8 @@ export function CopyTypeScriptPanel({
       )}
     >
       <div>
-        <p className="font-medium text-sm mb-2">TypeScript Definitions</p>
+        <p className="font-medium text-sm mb-2">{t.typeScriptDefinitions}</p>
-        <p className="text-xs text-fd-muted-foreground">Use the {name} type in TypeScript.</p>
+        <p className="text-xs text-fd-muted-foreground">{useTypeText}</p>
       </div>
       <button
         onClick={onCopy}
@@ -48,7 +51,7 @@ export function CopyTypeScriptPanel({
         )}
       >
         {isChecked ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
-        Copy
+        {t.copy}
       </button>
     </div>
   );

packages/openapi/src/ui/operation/index.tsx

@@ -1,4 +1,4 @@
-import { type ComponentProps, Fragment, type ReactNode } from 'react';
+import { ComponentProps, Fragment, type ReactNode } from 'react';
 import type {
   CallbackObject,
   MethodInformation,
@@ -11,6 +11,7 @@ import { Schema } from '../schema';
 import { UsageTabs } from '@/ui/operation/usage-tabs';
 import { Badge, MethodLabel } from '@/ui/components/method-label';
 import { CopyTypeScriptPanel, SelectTab, SelectTabs, SelectTabTrigger } from './client';
+import { I18nLabel } from '@/ui/client/i18n';
 import {
   AccordionContent,
   AccordionHeader,
@@ -19,18 +20,13 @@ import {
   AccordionTrigger,
 } from '@/ui/components/accordion';
 import { isMediaTypeSupported } from '@/requests/media/adapter';
-import { cn } from '@/utils/cn';
 import { APIPlayground } from '@/playground';
 import { getExampleRequests, RequestTabs } from './request-tabs';
 import { UsageTabsProviderLazy } from './usage-tabs/lazy';
 import { ServerProviderLazy } from '../contexts/api.lazy';
+import { cn } from '@/utils/cn';
 
-const ParamTypes = {
+const paramTypeKeys = ['path', 'query', 'header', 'cookie'] as const;
-  path: 'Path Parameters',
-  query: 'Query Parameters',
-  header: 'Header Parameters',
-  cookie: 'Cookie Parameters',
-};
 
 export async function Operation({
   type = 'operation',
@@ -80,7 +76,8 @@ export async function Operation({
     bodyNode = (
       <SelectTabs defaultValue={items[0].value}>
         <div className="flex gap-2 items-center justify-between mt-10">
-          {ctx.renderHeading(headingLevel, 'Request Body', {
+          {ctx.renderHeading(headingLevel, <I18nLabel label="titleRequestBody" />, {
+            id: 'request-body',
             className: 'my-0!',
           })}
           {contentTypes.length > 1 ? (
@@ -130,7 +127,9 @@ export async function Operation({
 
     responseNode = (
       <>
-        {ctx.renderHeading(headingLevel, 'Response Body')}
+        {ctx.renderHeading(headingLevel, <I18nLabel label="titleResponseBody" />, {
+          id: 'response-body',
+        })}
 
         <Accordions type="multiple">
           {statuses.map((status) => (
@@ -141,13 +140,15 @@ export async function Operation({
     );
   }
 
-  const parameterNode = Object.entries(ParamTypes).map(([type, title]) => {
+  const parameterNode = paramTypeKeys.map((type) => {
     const params = method.parameters?.filter((param) => param.in === type);
     if (!params || params.length === 0) return;
 
     return (
       <Fragment key={type}>
-        {ctx.renderHeading(headingLevel, title)}
+        {ctx.renderHeading(headingLevel, <I18nLabel label={`${type}Parameters`} />, {
+          id: `parameters-${type}`,
+        })}
         <div className="flex flex-col">
           {params.map(
             (param) =>
@@ -206,7 +207,8 @@ export async function Operation({
     authNode = (
       <SelectTabs defaultValue={items[0].value}>
         <div className="flex items-start justify-between gap-2 mt-10">
-          {ctx.renderHeading(headingLevel, 'Authorization', {
+          {ctx.renderHeading(headingLevel, <I18nLabel label="authorization" />, {
+            id: 'authorization',
             className: 'my-0!',
           })}
           {items.length > 1 ? (
@@ -239,7 +241,8 @@ export async function Operation({
     callbacksNode = (
       <SelectTabs defaultValue={items[0].value}>
         <div className="flex justify-between gap-2 items-end mt-10">
-          {ctx.renderHeading(headingLevel, 'Callbacks', {
+          {ctx.renderHeading(headingLevel, <I18nLabel label="titleCallbacks" />, {
+            id: 'callbacks',
             className: 'my-0!',
           })}
           {callbacks.length > 1 ? (
@@ -483,16 +486,20 @@ function AuthScheme({
   if (scheme.type === 'http' || scheme.type === 'oauth2') {
     return (
       <AuthProperty
-        name="Authorization"
+        name={<I18nLabel label="authorization" />}
         type={
-          scheme.type === 'http' && scheme.scheme === 'basic' ? `Basic <token>` : 'Bearer <token>'
+          scheme.type === 'http' && scheme.scheme === 'basic' ? (
+            <I18nLabel label="authBasicTokenExample" />
+          ) : (
+            <I18nLabel label="authBearerTokenExample" />
+          )
         }
         deprecated={scheme.deprecated}
         scopes={scopes}
       >
         {scheme.description && ctx.renderMarkdown(scheme.description)}
         <p>
-          In: <code>header</code>
+          <I18nLabel label="authTokenIn" />: <code>header</code>
         </p>
       </AuthProperty>
     );
@@ -508,7 +515,7 @@ function AuthScheme({
       >
         {scheme.description && ctx.renderMarkdown(scheme.description)}
         <p>
-          In: <code>{scheme.in}</code>
+          <I18nLabel label="authTokenIn" />: <code>{scheme.in}</code>
         </p>
       </AuthProperty>
     );
@@ -517,7 +524,7 @@ function AuthScheme({
   if (scheme.type === 'openIdConnect') {
     return (
       <AuthProperty
-        name="OpenID Connect"
+        name={<I18nLabel label="openIdConnect" />}
         type="<token>"
         deprecated={scheme.deprecated}
         scopes={scopes}
@@ -536,23 +543,28 @@ function AuthProperty({
   className,
   ...props
 }: ComponentProps<'div'> & {
-  name: string;
+  name: ReactNode;
-  type: string;
+  type: ReactNode;
   deprecated?: boolean;
   scopes?: string[];
+  children?: ReactNode;
 }) {
   return (
     <div className={cn('text-sm border-t my-4 first:border-t-0', className)}>
       <div className="flex flex-wrap items-center gap-3 not-prose">
         <span className="font-medium font-mono text-fd-primary">{name}</span>
         <span className="text-sm font-mono text-fd-muted-foreground">{type}</span>
-        {deprecated && <Badge color="red">Deprecated</Badge>}
+        {deprecated && (
+          <Badge color="red" className="text-xs">
+            <I18nLabel label="deprecated" />
+          </Badge>
+        )}
       </div>
       <div className="prose-no-margin pt-2.5 empty:hidden">
         {props.children}
         {scopes.length > 0 && (
           <p>
-            Scope: <code>{scopes.join(', ')}</code>
+            <I18nLabel label="authScope" />: <code>{scopes.join(', ')}</code>
           </p>
         )}
       </div>

packages/openapi/src/ui/operation/request-tabs.tsx

@@ -1,5 +1,6 @@
 import type { MethodInformation, RenderContext } from '@/types';
 import { getPreferredType, type NoReference, pickExample } from '@/utils/schema';
+import { I18nLabel } from '@/ui/client/i18n';
 import {
   AccordionContent,
   AccordionHeader,
@@ -165,16 +166,16 @@ function renderRequestTabsDefault(
     const displayNames: Partial<Record<keyof RawRequestData, ReactNode>> = {
       body: (
         <>
-          Body
+          <I18nLabel label="titleRequestBody" />
           <code className="text-xs text-fd-muted-foreground ms-auto">
             {requestData.bodyMediaType}
           </code>
         </>
       ),
-      cookie: 'Cookie',
+      cookie: <I18nLabel label="cookieParameters" />,
-      header: 'Header',
+      header: <I18nLabel label="headerParameters" />,
-      query: 'Query Parameters',
+      query: <I18nLabel label="queryParameters" />,
-      path: 'Path Parameters',
+      path: <I18nLabel label="pathParameters" />,
     };
 
     return (
@@ -213,7 +214,7 @@ function renderRequestTabsDefault(
         <TabsList>
           {items.map((item) => (
             <TabsTrigger key={item.id} value={item.id}>
-              {item.name}
+              {item.id === '_default' ? <I18nLabel label="requestTabNameDefault" /> : item.name}
             </TabsTrigger>
           ))}
         </TabsList>
@@ -227,12 +228,18 @@ function renderRequestTabsDefault(
   } else if (items.length === 1) {
     children = renderItem(items[0]);
   } else {
-    children = <p className="text-fd-muted-foreground text-xs">Empty</p>;
+    children = (
+      <p className="text-fd-muted-foreground text-xs">
+        <I18nLabel label="empty" />
+      </p>
+    );
   }
 
   return (
     <div className="p-3 rounded-xl border prose-no-margin bg-fd-card text-fd-card-foreground shadow-md">
-      <p className="font-semibold border-b pb-2">Example Requests</p>
+      <p className="font-semibold border-b pb-2">
+        <I18nLabel label="titleRequestTabs" />
+      </p>
       {children}
     </div>
   );

packages/openapi/src/ui/operation/response-tabs.tsx

@@ -10,6 +10,7 @@ import {
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import { sample } from 'openapi-sampler';
 import type { ReactNode } from 'react';
+import { I18nLabel } from '@/ui/client/i18n';
 
 export interface ResponseTab {
   /**
@@ -32,7 +33,7 @@ interface ResponseExample {
    */
   sample: unknown;
 
-  label: string;
+  label: ReactNode;
 
   /**
    * description (in Markdown)
@@ -64,10 +65,8 @@ export function ResponseTabs({
       tab.examples ??= [];
 
       for (const [key, sample] of Object.entries(responseOfType.examples)) {
-        const title = sample?.summary || `Example ${key}`;
-
         tab.examples.push({
-          label: title,
+          label: sample?.summary ?? <I18nLabel label="responseTabName" replacements={{ key }} />,
           sample: sample.value,
           description: sample?.description,
         });
@@ -75,7 +74,7 @@ export function ResponseTabs({
     } else if (responseOfType?.example || responseOfType?.schema) {
       tab.examples ??= [];
       tab.examples.push({
-        label: 'Example',
+        label: <I18nLabel label="responseTabNameDefault" />,
         sample: responseOfType.example ?? sample(responseOfType.schema as object),
       });
     }
@@ -103,12 +102,12 @@ function renderResponseTabsDefault(
   async function renderResponse(tab: ResponseTab) {
     const { examples = [] } = tab;
 
-    let slot: ReactNode = 'Empty';
+    let slot: ReactNode = <I18nLabel label="empty" />;
     if (examples.length > 1) {
       slot = (
-        <Accordions type="single" className="pt-2" defaultValue={examples[0].label}>
+        <Accordions type="single" className="pt-2" defaultValue="0">
           {examples.map((example, i) => (
-            <AccordionItem key={i} value={example.label}>
+            <AccordionItem key={i} value={i.toString()}>
               <AccordionHeader>
                 <AccordionTrigger>{example.label}</AccordionTrigger>
               </AccordionHeader>

packages/openapi/src/ui/schema/client.tsx

@@ -16,7 +16,13 @@ import {
   useState,
 } from 'react';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from 'fumadocs-ui/components/tabs';
-import type { InfoTag, SchemaDataObjectProperty, SchemaUIGeneratedData } from '@/ui/schema';
+import { useTranslations } from '@/ui/client/i18n';
+import type {
+  InfoTag,
+  SchemaData,
+  SchemaDataObjectProperty,
+  SchemaUIGeneratedData,
+} from '@/ui/schema';
 import {
   Collapsible,
   CollapsibleContent,
@@ -139,23 +145,7 @@ function SchemaUIProperty({
       $ref: $type,
     });
   } else if (schema.type === 'array') {
-    if (variant === 'expand')
+    if (variant === 'expand') return <ArrayItemCollapsible schema={schema} />;
-      return (
-        <Collapsible className="my-2">
-          <CollapsibleTrigger
-            className={cn(
-              buttonVariants({ color: 'secondary', size: 'sm' }),
-              'group px-3 py-2 data-[state=open]:rounded-b-none',
-            )}
-          >
-            Array Item
-            <ChevronDown className="size-4 text-fd-muted-foreground group-data-[state=open]:rotate-180" />
-          </CollapsibleTrigger>
-          <CollapsibleContent className="-mt-px bg-fd-card px-3 rounded-lg rounded-tl-none border shadow-sm">
-            <SchemaUIProperty name="" $type={schema.item.$type} variant="expand" />
-          </CollapsibleContent>
-        </Collapsible>
-      );
 
     type = renderRef({
       pathName: name,
@@ -168,8 +158,8 @@ function SchemaUIProperty({
       {schema.description}
       {schema.infoTags && schema.infoTags.length > 0 && (
         <div className="flex flex-row gap-2 flex-wrap my-2 not-prose empty:hidden">
-          {schema.infoTags.map((tag) => (
+          {schema.infoTags.map((tag, i) => (
-            <InfoTag key={tag.label} tag={tag} />
+            <InfoTag key={i} tag={tag} />
           ))}
         </div>
       )}
@@ -183,6 +173,28 @@ function SchemaUIProperty({
   );
 }
 
+function ArrayItemCollapsible({ schema }: { schema: Extract<SchemaData, { type: 'array' }> }) {
+  const [open, setOpen] = useState(false);
+  const t = useTranslations();
+
+  return (
+    <Collapsible className="my-2" open={open} onOpenChange={setOpen}>
+      <CollapsibleTrigger
+        className={cn(
+          buttonVariants({ color: 'secondary', size: 'sm' }),
+          'group px-3 py-2 data-[state=open]:rounded-b-none',
+        )}
+      >
+        {open ? t.schemaHideArray : t.schemaShowArray}
+        <ChevronDown className="size-4 text-fd-muted-foreground group-data-[state=open]:rotate-180" />
+      </CollapsibleTrigger>
+      <CollapsibleContent className="-mt-px bg-fd-card px-3 rounded-lg rounded-tl-none border shadow-sm">
+        <SchemaUIProperty name="" $type={schema.item.$type} variant="expand" />
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
 interface ObjectSearchProps {
   properties: SchemaDataObjectProperty[];
   container?: ComponentProps<'div'>;
@@ -194,6 +206,7 @@ function ObjectSearch({ properties, container, open }: ObjectSearchProps) {
   const deferredValue = useDeferredValue(search);
   const firstItemRef = useRef<SchemaDataObjectProperty>(null);
   const prevProperties = useRef(properties);
+  const t = useTranslations();
 
   if (prevProperties.current !== properties) {
     prevProperties.current = properties;
@@ -214,7 +227,7 @@ function ObjectSearch({ properties, container, open }: ObjectSearchProps) {
           value={search}
           data-object-search-input=""
           onChange={(e) => setSearch(e.target.value)}
-          placeholder="Filter Properties"
+          placeholder={t.schemaFilterPropertiesPlaceholder}
           className="text-sm ps-2 py-2 flex-1 outline-none placeholder:text-fd-muted-foreground"
           onKeyDown={(e) => {
             if (e.key === 'Enter' && open) {
@@ -244,6 +257,7 @@ function ObjectSearchContent({
   firstItemRef: RefObject<SchemaDataObjectProperty | null>;
   properties: SchemaDataObjectProperty[];
 }) {
+  const t = useTranslations();
   const filtered = useMemo(() => {
     const search = rawSearch.trim().toLowerCase();
     return search.length > 0
@@ -256,7 +270,7 @@ function ObjectSearchContent({
   if (filtered.length === 0)
     return (
       <p className="text-fd-muted-foreground text-sm px-2">
-        No property matching{' '}
+        {t.schemaFilterPropertiesEmpty}{' '}
         <span className="text-fd-foreground font-medium">{`"${rawSearch}"`}</span>
       </p>
     );
@@ -504,6 +518,7 @@ function Property({
   className,
   ...props
 }: PropertyProps) {
+  const t = useTranslations();
   return (
     <div
       className={cn(
@@ -530,7 +545,7 @@ function Property({
         )}
         {deprecated && (
           <Badge color="yellow" className="ms-auto text-xs">
-            Deprecated
+            {t.deprecated}
           </Badge>
         )}
       </div>

packages/openapi/src/ui/schema/index.tsx

@@ -5,6 +5,7 @@ import { FormatFlags, schemaToString } from '@/utils/schema-to-string';
 import { mergeAllOf } from '@/utils/merge-schema';
 import type { SchemaUIProps } from '@/ui/schema/client';
 import { SchemaUILazy } from '@/ui/schema/lazy';
+import { I18nLabel } from '../client/i18n';
 
 export interface FieldBase {
   description?: ReactNode;
@@ -17,7 +18,7 @@ export interface FieldBase {
 }
 
 export interface InfoTag {
-  label: string;
+  label: ReactNode;
   value: string;
 }
 
@@ -101,19 +102,25 @@ export function generateSchemaUI(
     const fields: InfoTag[] = [];
 
     if (schema.default !== undefined) {
-      fields.push({ label: 'Default', value: JSON.stringify(schema.default) });
+      fields.push({
+        label: <I18nLabel label="schemaDefault" />,
+        value: JSON.stringify(schema.default),
+      });
     }
 
     if (schema.pattern) {
-      fields.push({ label: 'Match', value: schema.pattern });
+      fields.push({ label: <I18nLabel label="schemaMatch" />, value: schema.pattern });
     }
 
     if (schema.format) {
-      fields.push({ label: 'Format', value: schema.format });
+      fields.push({ label: <I18nLabel label="schemaFormat" />, value: schema.format });
     }
 
     if (schema.multipleOf) {
-      fields.push({ label: 'Multiple Of', value: schema.multipleOf.toString() });
+      fields.push({
+        label: <I18nLabel label="schemaMultipleOf" />,
+        value: schema.multipleOf.toString(),
+      });
     }
 
     let range = formatRange(
@@ -123,10 +130,10 @@ export function generateSchemaUI(
       schema.maximum,
       schema.exclusiveMaximum,
     );
-    if (range) fields.push({ label: 'Range', value: range });
+    if (range) fields.push({ label: <I18nLabel label="schemaRange" />, value: range });
 
     range = formatRange('length', schema.minLength, undefined, schema.maxLength, undefined);
-    if (range) fields.push({ label: 'Length', value: range });
+    if (range) fields.push({ label: <I18nLabel label="schemaLength" />, value: range });
 
     range = formatRange(
       'properties',
@@ -135,21 +142,24 @@ export function generateSchemaUI(
       schema.maxProperties,
       undefined,
     );
-    if (range) fields.push({ label: 'Properties', value: range });
+    if (range) fields.push({ label: <I18nLabel label="schemaProperties" />, value: range });
 
     range = formatRange('items', schema.minItems, undefined, schema.maxItems, undefined);
-    if (range) fields.push({ label: 'Items', value: range });
+    if (range) fields.push({ label: <I18nLabel label="schemaItems" />, value: range });
 
     if (schema.enum) {
       fields.push({
-        label: 'Value in',
+        label: <I18nLabel label="schemaValueIn" />,
         value: schema.enum.map((value) => JSON.stringify(value)).join(' | '),
       });
     }
 
     if (showExample && schema.examples) {
       for (const example of schema.examples) {
-        fields.push({ label: 'Example', value: JSON.stringify(example, null, 2) });
+        fields.push({
+          label: <I18nLabel label="schemaExample" />,
+          value: JSON.stringify(example, null, 2),
+        });
       }
     }
 

packages/openapi/tsdown.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
   format: 'esm',
   target: 'es2023',
   entry: [
-    './src/index.ts',
+    './src/{index,i18n}.ts',
     './src/ui/index.ts',
     './src/ui/base.tsx',
     './src/ui/client/index.tsx',

packages/radix-ui/src/i18n.tsx

@@ -10,15 +10,22 @@ export interface I18nUIConfig<Languages extends string> extends I18nConfig<Langu
   provider: (locale?: Languages | (string & {})) => I18nProviderProps;
 }
 
+type TranslationsConfig<Languages extends string> = {
+  [K in Languages]?: Partial<Translations> & { displayName?: string };
+};
+
 export function defineI18nUI<Languages extends string>(
   config: I18nConfig<Languages>,
-  options: {
+  options:
-    translations: {
+    | {
-      [K in Languages]?: Partial<Translations> & { displayName?: string };
+        /**
-    };
+         * @deprecated you can directly define the translations in outer scope (the parent object of `translations`)
-  },
+         */
+        translations: TranslationsConfig<Languages>;
+      }
+    | TranslationsConfig<Languages> = {},
 ): I18nUIConfig<Languages> {
-  const { translations } = options;
+  const translations = 'translations' in options ? options.translations : options;
 
   return {
     ...config,

pnpm-lock.yaml

@@ -2409,6 +2409,9 @@ importers:
 
   packages/openapi:
     dependencies:
+      '@fastify/deepmerge':
+        specifier: ^3.2.1
+        version: 3.2.1
       '@fumari/json-schema-ts':
         specifier: ^0.0.2
         version: 0.0.2([email protected])