مدونة

اجعل Claude Code يترجم نص واجهة المستخدم أثناء كتابته

طلب ميزة واحدة في تطبيق Next.js بثلاث لغات: الإعداد، رسالة الخطاف، استدعاء الترجمة، الترجمات والفحص، من جلسة Claude Code حقيقية.

Stephen Ufort · 16 نوفمبر 2026 · 5 دقائق للقراءة

طلب الميزة في Claude Code، واستدعاء الترجمة مع إحصائياته، ورسالة التأكيد بالإسبانية والألمانية والفرنسية، والفحص الناجح

يكتب Claude Code نص واجهة المستخدم باللغة الإنجليزية، حيثما تحتاج الميزة إليه. في تطبيق مترجم بالفعل، تترك كل ميزة جديدة بضع سلاسل نصية مكتوبة بشكل ثابت. يتبع هذا المنشور طلب ميزة واحدة في تطبيق Next.js بالإسبانية والألمانية والفرنسية، من الإعداد إلى الفحص الناجح، مع الأوامر والمخرجات الحقيقية.

التطبيق هو تطبيق الملاحظات من المنشور حول إضافة i18n إلى تطبيق Next.js App Router في طلب سحب واحد. يحتوي بالفعل على i18next وملفات محلية ومبدل لغة. كيفية عمل خادم MCP والخطاف داخليًا موجود في المنشور حول الترجمة أثناء كتابة وكيل الترميز الخاص بك؛ هذا المنشور يوضحها في تغيير حقيقي.

إعدادها

أمر واحد يضيف خادم MCP، وخطاف ما بعد التحرير، وتعليمات الوكيل:

$ npx localize-dev init --agent
🤖 Wrote .mcp.json
🤖 Wrote .cursor/mcp.json
🤖 Wrote .claude/settings.json
🤖 Wrote AGENTS.md
🤖 Wrote CLAUDE.md
🤖 Wrote .cursor/rules/localize.mdc
Commit these so everyone working on the project, and their agents, gets them. Restart the agent to load the MCP server.

يذهب الخطاف في .claude/settings.json. بعد كل تحرير أو تحرير متعدد أو كتابة، يقوم Claude Code بتشغيل localize-dev hook على الملف الذي قام الوكيل بتغييره:

.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y localize-dev hook",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

يحصل AGENTS.md على قسم قصير، ويقوم CLAUDE.md باستيراده، لذا يقرأه Claude Code في بداية كل جلسة:

AGENTS.md
## Translations (localize.dev)

The UI text is translated with localize.dev, so text people see goes through the i18n library and isn't hardcoded.

- After adding or changing UI text, call the `localize` tool of the localize-dev MCP server with the files you changed (`paths`, relative to the source folder `src`). It gives the text keys, rewrites the code and translates the new messages. Without the MCP server, run `npx localize-dev run --files <files>`.
- Before finishing, run `npx localize-dev check --changed`. It should pass.
- Leave new messages out of the other languages' locale files: localize fills them in. Fixing a translation that's wrong is fine.

قم بتثبيت الملفات حتى يحصل باقي الفريق، ووكلاؤهم، عليها أيضًا. ثم أعد تشغيل Claude Code ليبدأ خادم MCP.

اطلب ميزة

هذا هو الطلب بأكمله. لا يذكر الترجمات:

the prompt
Add a delete button to each note in the notes list. Ask for confirmation before removing a note, and show a short message after it's deleted.

قرأ Claude Code كود الملاحظات، ثم كتب إجراء خادم يحذف ملاحظة، ووظيفة حذف في طبقة البيانات، و NoteList الجديد: زر حذف على كل ملاحظة، وتأكيد داخل الصف، ورسالة بعد الحذف، ورسالة خطأ إذا فشل. احتوت المسودة الأولى على سبع قطع نصية باللغة الإنجليزية.

ما يراه الخطاف

إليك ما يطبعه الخطاف لتلك المسودة الأولى. وجد السبعة جميعًا، بما في ذلك aria-label واثنين من قوالب الحروف:

hook output
localize.dev: src/components/NoteList.tsx has UI text that isn't translated yet.
  line 41: "Deleted "{deletedTitle}"."
  line 43: "Couldn't delete the note. Try again."
  line 54: "Delete "{title}"?"
  line 56: "Delete"
  line 59: "Cancel"
  line 63: "Delete "{title}""
  line 64: "Delete"
Call the localize tool of the localize-dev MCP server with paths ["components/NoteList.tsx"]: it gives this text translation keys, rewrites the code and translates it.
Without the MCP server, run in the project folder: npx localize-dev run --files src/components/NoteList.tsx

يخرج الخطاف بالرمز 2، لذا يعرض Claude Code هذه الرسالة للوكيل. يخرج ملف لا يحتوي على شيء لترجمته بالرمز 0 ولا يطبع شيئًا. لإيقاف تشغيل الخطاف لجلسة، اضبط LOCALIZE_DEV_HOOK=off.

استدعاء التوطين

مباشرة بعد كتابة المكون، استدعى الوكيل الأداة localize بهذا المسار. هذه هي المكالمة والإحصائيات من نتيجتها:

localize tool call and result
localize({ "paths": ["components/NoteList.tsx"] })

"stats": {
  "filesScanned": 1,
  "stringsReplaced": 7,
  "newKeys": 6,
  "reusedKeys": 1,
  "translations": { "es": 6, "de": 6, "fr": 6 }
}

أصبحت سبع سلاسل نصية ستة مفاتيح: زري الحذف يتشاركان note_list.delete_button. أصبحت قوالب الحروف رسائل تحتوي على عناصر نائبة، لذا فإن Delete "${n.title}" هي الآن رسالة واحدة تحتوي على عنصر نائب title، ويمكن للغة وضع العنوان في أي مكان تحتاجه قواعدها. يبدو صف التأكيد الآن كالتالي:

src/components/NoteList.tsx
{confirmingId === n.id ? (
  <div className="flex items-center gap-2 text-sm">
    <span>{t('note_list.delete_note_confirmation', { title: n.title })}</span>
    <button type="button" onClick={() => remove(n)} disabled={pending} className="rounded bg-red-600 px-3 py-1 text-white disabled:opacity-50">
      {t('note_list.delete_button')}
    </button>
    <button type="button" onClick={() => setConfirmingId(null)} disabled={pending} className="rounded border px-3 py-1">
      {t('note_list.cancel')}
    </button>
  </div>
) : (
  <button type="button" onClick={() => { setConfirmingId(n.id); setFailed(false); }} aria-label={t('note_list.delete_note_button_label', { title: n.title })} className="rounded border px-3 py-1 text-sm text-red-600">
    {t('note_list.delete_button')}
  </button>
)}

الترجمات

نفس الاستدعاء مملوء باللغتين الإسبانية والألمانية والفرنسية. هذه هي الإضافات الألمانية:

locales/de.json
"deleted_note_message": "„{{deletedTitle}}“ gelöscht.",
"delete_note_error": "Die Notiz konnte nicht gelöscht werden. Versuchen Sie es erneut.",
"delete_note_confirmation": "„{{title}}“ löschen?",
"delete_button": "Löschen",
"cancel": "Abbrechen",
"delete_note_button_label": "„{{title}}“ löschen"

يستخدم الألمانية علامات الاقتباس الخاصة بها وصيغة المخاطب الرسمية Sie ("Versuchen Sie es erneut")، وهي نفس المستخدمة في بقية التطبيق. حصلت الفرنسية على « » مع مسافات بداخلها. تستخدم الإسبانية صيغة tú، كما في الرسائل السابقة:

locales/es.json
"deleted_note_message": "Se eliminó \"{{deletedTitle}}\".",
"delete_note_error": "No se pudo eliminar la nota. Inténtalo de nuevo.",
"delete_note_confirmation": "¿Eliminar \"{{title}}\"?",
"delete_button": "Eliminar",
"cancel": "Cancelar",
"delete_note_button_label": "Eliminar \"{{title}}\""

لم يكتب الوكيل أيًا من هذه يدويًا. يطلب القسم في AGENTS.md منه ترك ملفات اللغة للغات الأخرى وشأنها، وقد فعل ذلك.

تم التحقق قبل الانتهاء

قبل أن يعلن عن اكتماله، قام الوكيل بتشغيل الفحص، ثم مدقق الأنواع ومدقق الأكواد:

$ npx localize-dev check --changed
✅ Everything is localized (1 files scanned).

قال ملخصه ثلاثة أشياء مفيدة. لقد بنى التأكيد في الصف بدلاً من استخدام نافذة المتصفح المنبثقة الخاصة به، لذلك يمكن ترجمة النص. تعود الملاحظات المحذوفة عند إعادة تشغيل الخادم، لأن طبقة البيانات هي بديل مؤقت. ولم يحاول استخدام الميزة في متصفح. جربها بنفسك قبل الدمج: يغطي الفحص النص، وليس ما إذا كان الحذف يعمل.

مؤشر وعوامل أخرى

يحصل المؤشر على نفس خادم MCP في .cursor/mcp.json وقاعدة في .cursor/rules/localize.mdc لملفات واجهة المستخدم الخاصة بالتطبيق. init --agent لا يضيف أي خطاف للمؤشر، لذا فإن القاعدة هي ما يطلب من الوكيل استدعاء localize. العوامل الأخرى التي تقرأ AGENTS.md تحصل على نفس التعليمات، ويمكن للعامل بدون MCP تشغيل npx localize-dev run --files بالملفات التي قام بتغييرها.

بالنسبة للتغييرات التي تم إجراؤها بدون وكيل، يتحقق npx localize-dev init --agent --pre-commit أيضًا من الملفات المرحلية قبل كل تثبيت، ويفشل npx localize-dev check في CI طلب سحب بنص ثابت. لا يحتاج أي منهما إلى مفتاح API.

لا يزال يتعين على شخص يقرأ كل لغة إلقاء نظرة على ملفات اللغة في الفرق. يحتفظ التشغيل بشكل واحد من العناوين لكل لغة، ولكن القارئ فقط هو من يعرف ما إذا كانت "Löschen" هي الكلمة التي يتوقعها المستخدمون الألمان على هذا الزر.

جربه على الكود الخاص بك في الملعب، لا يلزم حساب