BuilderIO/agent-native / packages/core/docs
agent-native-docs
UnverifiedHow to look up version-matched Agent-Native framework docs and source in node_modules. Use before coding against @agent-native/core APIs or advanced features.
content/locales/ar-SA/internationalization.mdx
View on GitHub---
title: "التدويل"
description: "قم بترجمة تطبيقات Agent-Native باستخدام كتالوجات محلية مشتركة، ومنتقي اللغة، ولغة احتياطية للمتصفح."
---
# التدويل
يمكن لتطبيقات Agent-Native توطين إطار العمل والنموذج UI من خلال
وقت تشغيل `@agent-native/core/client/i18n` المشترك. يقوم الإطار بتخزين
اختيار اللغة الخاص بالمستخدم في إعدادات SQL، ويعرضه كـ actions، ويعود إلى
الإنجليزية عندما لا يكون التطبيق قد ترجم سلسلة نصية بعد.
## وقت التشغيل
استخدم الموفر من خلال `AppProviders`:
```tsx
import { AppProviders } from "@agent-native/core/client/hooks";
import { getLocaleInitScript } from "@agent-native/core/client/i18n";
import { i18nCatalog } from "./i18n";
const LOCALE_INIT_SCRIPT = getLocaleInitScript();
<script
data-agent-native-locale-init
dangerouslySetInnerHTML={{ __html: LOCALE_INIT_SCRIPT }}
/>;
<AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
<Outlet />
</AppProviders>;
```
يقوم `getLocaleInitScript()` بتعيين `lang` و`dir` الأوليين، وكذلك
`window.__AGENT_NATIVE_LOCALE__`، قبل أن يقوم React بعملية الـ hydrate. يمكن لمسارات SSR
العامة استدعاء `resolveLocaleFromRequest()` من `@agent-native/core/server` وتمرير
اللغة المحلية/الكتالوج الناتجين إلى هذا البرنامج النصي لتجنب أي تعارض في الـ hydration.
## الكتالوجات
يحتفظ كل قالب مترجم بالكتالوجات ضمن `app/i18n/`:
```ts filename="app/i18n/index.ts"
import { createAgentNativeI18nCatalog } from "@agent-native/core/client/i18n";
import enUS from "./en-US";
export const i18nCatalog = createAgentNativeI18nCatalog({
messages: enUS,
localeLoaders: {
"zh-CN": () => import("./zh-CN"),
"zh-TW": () => import("./zh-TW"),
"es-ES": () => import("./es-ES"),
"fr-FR": () => import("./fr-FR"),
"de-DE": () => import("./de-DE"),
"ja-JP": () => import("./ja-JP"),
"ko-KR": () => import("./ko-KR"),
"pt-BR": () => import("./pt-BR"),
"hi-IN": () => import("./hi-IN"),
"ar-SA": () => import("./ar-SA"),
},
});
```
يقوم `messages` بحزم `en-US` مباشرة بحيث تكون متاحة دائمًا قبل تحميل أي
لغة أخرى. يقوم `localeLoaders` باستيراد كل كتالوج آخر بشكل ديناميكي حتى لا يقوم
المستخدمون بتنزيل سوى اللغة النشطة. رموز اللغات المدعومة هي `en-US`،
و`zh-CN`، و`zh-TW`، و`es-ES`، و`fr-FR`، و`de-DE`، و`ja-JP`، و`ko-KR`، و`pt-BR`،
و`hi-IN`، و`ar-SA`.
يوفر إطار العمل لغات مدمجة، ويمكن للتطبيقات تسجيل لغات BCP-47 إضافية
ببياناتها الوصفية، مثل الاسم المحلي والاسم الإنجليزي واتجاه النص. استخدم
`coreMessageOverrides` لترجمات إطار العمل الاختيارية؛ وتعود المفاتيح المفقودة
إلى الإنجليزية.
يقبل `createAgentNativeI18nCatalog` أيضًا معامل `sourceLocale` اختياريًا،
والذي تكون قيمته الافتراضية `en-US`، ومصفوفة `supportedLocales` اختيارية. اضبط
`supportedLocales` عندما يشحن التطبيق ترجمات لبعض لغات إطار العمل فقط بدلاً
من العشر لغات كلها. تكون قيمته الافتراضية كل لغة يدعمها إطار العمل. لا يسرد
`LanguagePicker` سوى اللغات ضمن هذه المجموعة، وأي لغة مكتشفة أو مطلوبة خارج
هذه المجموعة تعود إلى `sourceLocale`.
تُضاف اللغات المسجلة في `locales` إلى هذه القائمة حتى عند تقييد اللغات
المدمجة عبر `supportedLocales`. أما `translations.locales` في
`agent-native.json` فهي قائمة سماح صريحة للتطبيق وتتقدم على تسجيل الكتالوج.
## UI
استخدم `useT()` لترجمة سلاسل الواجهة:
```tsx
import { useT } from "@agent-native/core/client/i18n";
function Greeting({ name }: { name: string }) {
const t = useT();
return <p>{t("greeting.hello", { name })}</p>;
}
```
استخدم `useFormatters()` للتواريخ والأرقام والوقت النسبي والقوائم. لا تضع
تنسيق التاريخ/الأرقام الحساس للغة المحلية داخل سلاسل الترجمة.
تتضمن الإعدادات صف **Interface language** في Account › Preferences، ويسري التغيير هناك
على كل التطبيقات، لذلك لا تضيف صفحات إعدادات التطبيق أداة اختيار ثانية.
ضع `<LanguagePicker />` في أي مكان آخر يتيح فيه التطبيق للمستخدم تغيير لغته، مثل اختصار
في الترويسة. راجع [Toolkit: Settings](/docs/toolkit-settings) لمعرفة عقد صفحة الإعدادات.
## Actions والإصرار
يرث كل تطبيق:
- `get-localization-preference` — اقرأ `{ locale, timezone }` الخاصين بالمستخدم الحالي
- `set-localization-preference` — عيّن `locale` و/أو `timezone`، وكل منهما اختياري
`locale` إما `"system"` أو لغة محلية صالحة مسجلة بواسطة التطبيق وفق BCP-47. `timezone` إما
`"system"` أو منطقة زمنية IANA مثل `America/New_York`. يوجد هذا الحقل حتى
تعمل المهام المجدولة والتلقائية في المنطقة الزمنية للمستخدم بدلاً من منطقة
المضيف. ترك حقل واحد فقط عند التعيين يُبقي الحقل الآخر دون تغيير، لأن
`set-localization-preference` يدمج القيمة الجديدة مع القيمة المخزنة الحالية
بدلاً من الكتابة فوقها.
تتواجد القيمة الدائمة في إعدادات SQL على نطاق المستخدم ضمن `localization`.
يُستخدم `localStorage` فقط قبل عملية الـ hydrate وكاحتياط للمستخدمين المجهولين.
يتم عكس اللغة النشطة في حالة التطبيق كسياق محيط حتى يتمكن الوكلاء من رؤية
لغة الواجهة الحالية.
## حارس
شغّل:
```bash
pnpm guard:i18n-catalogs
```
بالنسبة لكتالوجات التطبيقات والقوالب، يتحقق الحارس من:
- أسماء ملفات اللغات، وتكافؤ المفاتيح، وتكافؤ العناصر النائبة، والمفاتيح القديمة
- المفاتيح المكررة والعلامات المتبقية من مرحلة التطوير فقط
- تلوث اللغة الخاطئة، على سبيل المثال نص صيني داخل كتالوج عربي
- فئات الجمع الخاصة بـ CLDR من خلال `Intl.PluralRules`
- استدعاءات `t()` في مصدر التطبيق التي يكون مفتاحها مفقودًا من الكتالوج الإنجليزي
يتحقق الحارس من البنية، وليس من جودة الترجمة. لا تزال السلاسل عالية
الظهور بحاجة إلى مراجعة بشرية.
لا تترجم المعرّفات الثابتة مثل أسماء actions، والمسارات، وقيم التعداد،
ومفاتيح حالة التطبيق، وقيم قاعدة البيانات، وحقول البروتوكول، وأسماء متغيرات
env، وأسماء الموفرين.
## الخطوات التالية
- [**نظرة عامة**](/docs/client-overview#app-shell) — غلاف `AppProviders` وخطافات المتصفح الأخرى التي يُبنى عليها i18n
- [**Toolkit: Settings**](/docs/toolkit-settings) — عقد صفحة الإعدادات، حيث تتولى Account › Preferences لغة الواجهة
- [**البدء**](/docs/getting-started) — ابنِ تطبيقك الأول على قالب يشحن بالفعل كتالوجات مترجمة
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |