Twig - Lingo.dev CLI

ما هو Twig؟

Twig هو محرك قوالب مرن وسريع وآمن لـ PHP. يُستخدم على نطاق واسع في تطبيقات Symfony وأطر عمل PHP الأخرى لفصل منطق العرض عن منطق التطبيق. يستخدم Twig بناء جملة واضحاً يجعل القوالب سهلة القراءة والكتابة.

ما هو Lingo.dev CLI؟

Lingo.dev CLI هو واجهة سطر أوامر مجانية ومفتوحة المصدر لترجمة التطبيقات والمحتوى باستخدام الذكاء الاصطناعي. تم تصميمه ليحل محل برامج إدارة الترجمة التقليدية مع التكامل مع خطوط الأنابيب الحالية.

لمعرفة المزيد، راجع نظرة عامة.

حول هذا الدليل

يشرح هذا الدليل كيفية ترجمة قوالب Twig باستخدام Lingo.dev CLI.

ستتعلم كيفية:

إنشاء مشروع من الصفر
تكوين خط أنابيب الترجمة
إنشاء ترجمات باستخدام الذكاء الاصطناعي

المتطلبات الأساسية

لاستخدام Lingo.dev CLI، تأكد من تثبيت Node.js الإصدار 18 أو أحدث:

❯ node -v
v22.17.0

الخطوة 1. إعداد المشروع

في دليل مشروعك، أنشئ ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يحدد هذا الملف سلوك خط أنابيب الترجمة، بما في ذلك اللغات المراد الترجمة بينها ومكان وجود المحتوى القابل للترجمة على نظام الملفات.

لمعرفة المزيد حول الخصائص المتاحة، راجع i18n.json.

الخطوة 2. تكوين اللغة المصدر

اللغة المصدر هي اللغة والمنطقة الأصلية التي تمت كتابة المحتوى بها. لتكوين اللغة المصدر، قم بتعيين خاصية locale.source في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يجب توفير اللغة المصدر كـ علامة لغة BCP 47.

للحصول على القائمة الكاملة لرموز اللغات التي يدعمها Lingo.dev CLI، راجع رموز اللغات المدعومة.

الخطوة 3. تكوين اللغات المستهدفة

اللغات المستهدفة هي اللغات والمناطق التي تريد ترجمة المحتوى الخاص بك إليها. لتكوين اللغات المستهدفة، قم بتعيين خاصية locale.targets في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

الخطوة 4. إنشاء المحتوى المصدر

إذا لم تكن قد قمت بذلك بالفعل، قم بإنشاء ملف أو أكثر من ملفات قوالب Twig التي تحتوي على المحتوى المراد ترجمته. يجب أن تكون هذه الملفات موجودة في مسار يتضمن اللغة المصدر في مكان ما في المسار (على سبيل المثال، كاسم دليل مثل en/ أو كجزء من اسم الملف مثل template_en.html.twig).

بالنسبة لقوالب Twig، يتضمن المحتوى القابل للترجمة:

محتوى نصي داخل عناصر الكتلة: h1-h6، p، div، li، blockquote، article، section، إلخ.
محتوى نصي داخل العناصر المضمنة: a، strong، em، span، code، إلخ.
قيم السمات بما في ذلك:
- سمة content على وسوم meta
- سمات alt و title على وسوم img
- سمات placeholder و title و aria-label على وسوم input و textarea و button و a و abbr و link

كيفية التعامل مع صيغة Twig:

يتم الحفاظ على صيغة قالب Twig بالكامل أثناء الترجمة:

متغيرات وتعبيرات Twig ({{ user.name }}، {{ product.price|number_format }}) يتم الاحتفاظ بها كما هي داخل النص القابل للترجمة
هياكل التحكم في Twig ({% if %}، {% for %}، {% set %}) يتم الحفاظ عليها ولا تتم ترجمتها
تعليقات Twig ({# internal note #}) يتم الحفاظ عليها ولا تتم ترجمتها
مرشحات Twig ({{ "now"|date('Y') }}) تظل وظيفية في القوالب المترجمة

كيفية التعامل مع HTML المضمن:

عندما يحتوي النص على عناصر HTML مضمنة (مثل <strong>، <span>، <em>، <a>، إلخ.)، تتم ترجمة كتلة النص بأكملها كوحدة واحدة كاملة. يحافظ هذا على السياق لجودة ترجمة أفضل ويحافظ على التنسيق المضمن.

على سبيل المثال:

<p>Hello <strong>{{ user.name }}</strong>, welcome back!</p>

تتم ترجمة الفقرة بأكملها "Hello <strong>{{ user.name }}</strong>, welcome back!" ككتلة واحدة، مع الحفاظ على كل من وسوم <strong> ومتغير Twig في مكانهما. يضمن ذلك حصول مترجم الذكاء الاصطناعي على السياق الكامل والحفاظ على كل من التنسيق المضمّن وبناء جملة Twig في الترجمة.

سمة lang التلقائية:

يتم تحديث سمة lang على عنصر <html> تلقائيًا لتتطابق مع اللغة المستهدفة:

<!-- Source (en/template.html.twig) -->
<html>
<head>
    <title>Welcome</title>
</head>

<!-- Target (es/template.html.twig) -->
<html lang="es">
<head>
    <title>Bienvenido</title>
</head>

المحتوى غير القابل للترجمة:

لا تتم ترجمة المحتوى الموجود داخل وسوم <script> و <style>.

الخطوة 5. إنشاء حاوية

في ملف i18n.json، أضف كائن "twig" إلى كائن buckets:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {}
  }
}

في كائن "twig"، حدد مصفوفة من نمط واحد أو أكثر من أنماط include:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {
      "include": ["./[locale]/*.twig"]
    }
  }
}
```
تحدد هذه الأنماط الملفات المراد ترجمتها.

الأنماط نفسها:
- يجب أن تحتوي على [locale] كعنصر نائب للغة المكوّنة
- يمكن أن تشير إلى مسارات الملفات (مثل "[locale]/template.html.twig")
- يمكن استخدام النجوم كعناصر نائبة بدل (مثل "[locale]/*.twig")
أنماط glob العودية (مثل **/*.twig) غير مدعومة.

الخطوة 6. تكوين نموذج لغوي كبير

يستخدم Lingo.dev CLI نماذج لغوية كبيرة (LLMs) لترجمة المحتوى بالذكاء الاصطناعي. لاستخدام أحد هذه النماذج، تحتاج إلى مفتاح API من مزود مدعوم.

للبدء بأسرع ما يمكن، نوصي باستخدام Lingo.dev Engine:

سجّل للحصول على حساب Lingo.dev.
قم بتشغيل الأمر التالي:
```
npx lingo.dev@latest login
```
سيؤدي ذلك إلى فتح متصفحك الافتراضي ومطالبتك بالمصادقة.
اتبع التعليمات.

الخطوة 7. إنشاء الترجمات

في الدليل الذي يحتوي على ملف i18n.json، قم بتشغيل الأمر التالي:

npx lingo.dev@latest run

يقوم هذا الأمر بـ:

قراءة ملف i18n.json.
العثور على الملفات التي تحتاج إلى ترجمة.
استخراج المحتوى القابل للترجمة من الملفات.
استخدام نموذج اللغة الكبير المُكوَّن لترجمة المحتوى المستخرج.
كتابة المحتوى المترجم مرة أخرى إلى نظام الملفات.

عند إنشاء الترجمات للمرة الأولى، يتم إنشاء ملف i18n.lock. يتتبع هذا الملف المحتوى الذي تمت ترجمته، مما يمنع إعادة الترجمة غير الضرورية في عمليات التشغيل اللاحقة.

مثال

en/example.html.twig

{% set user = app.user %}
<!DOCTYPE html>
<html>
<head>
    <meta name="description" content="Welcome to our application">
    <title>Welcome</title>
</head>
<body>
    <header>
        <nav>
            <a href="/" title="Go to homepage">Home</a>
            <a href="/about" title="Learn more about us">About</a>
            <a href="/contact" title="Get in touch">Contact</a>
        </nav>
    </header>

    <main>
        <section class="hero">
            <h1>Welcome to Our Platform</h1>
            <p>Hello <strong>{{ user.name }}</strong>, we're glad to have you here!</p>
            <p>Start exploring our features and discover what makes us <em>unique</em>.</p>
        </section>

        {% if user.isPremium %}
        <section class="premium-benefits">
            <h2>Premium Benefits</h2>
            <ul>
                <li>Unlimited access to all features</li>
                <li>Priority customer support</li>
                <li>Advanced analytics and reporting</li>
            </ul>
        </section>
        {% endif %}

        <section class="getting-started">
            <h2>Getting Started</h2>
            <p>Follow these simple steps to begin your journey:</p>
            <ol>
                <li>Complete your profile</li>
                <li>Explore the dashboard</li>
                <li>Invite your team members</li>
            </ol>

            <form action="/profile/update" method="post">
                <label for="bio">Tell us about yourself:</label>
                <textarea id="bio" name="bio" placeholder="Enter your bio here" aria-label="User biography"></textarea>

                <label for="email">Email address:</label>
                <input type="email" id="email" name="email" placeholder="[email protected]" aria-label="Email address">

                <button type="submit" title="Save your profile changes">Save Profile</button>
            </form>
        </section>

        {# This section is for internal notes and won't be displayed #}
        {% if app.debug %}
        <section class="debug-info">
            <h3>Debug Information</h3>
            <p>User ID: {{ user.id }}</p>
            <p>Last login: {{ user.lastLogin|date('Y-m-d H:i:s') }}</p>
        </section>
        {% endif %}
    </main>

    <footer>
        <p>Need help? <a href="/support" title="Visit our support center">Contact Support</a></p>
        <p>&copy; {{ "now"|date('Y') }} Our Company. All rights reserved.</p>
    </footer>
</body>
</html>

es/example.html.twig

{% set user = app.user %}
<!DOCTYPE html>
<html lang="es">
<head>
    <meta name="description" content="Bienvenido a nuestra aplicación">
    <title>Bienvenido</title>
</head>
<body>
    <header>
        <nav><a href="/" title="Ir a la página de inicio">Inicio</a>
            <a href="/about" title="Conoce más sobre nosotros">Acerca de</a>
            <a href="/contact" title="Ponte en contacto">Contacto</a></nav>
    </header>

    <main>
        <section class="hero">
            <h1>Bienvenido a nuestra plataforma</h1>
            <p>Hola <strong>{{ user.name }}</strong>, nos alegra tenerte aquí!</p>
            <p>Comienza a explorar nuestras funciones y descubre lo que nos hace <em>únicos</em>.</p>
        </section>

        {% if user.isPremium %}
        <section class="premium-benefits">
            <h2>Beneficios premium</h2>
            <ul>
                <li>Acceso ilimitado a todas las funciones</li>
                <li>Soporte prioritario al cliente</li>
                <li>Análisis y reportes avanzados</li>
            </ul>
        </section>
        {% endif %}

        <section class="getting-started">
            <h2>Primeros pasos</h2>
            <p>Sigue estos sencillos pasos para comenzar tu experiencia:</p>
            <ol>
                <li>Completa tu perfil</li>
                <li>Explora el panel de control</li>
                <li>Invita a los miembros de tu equipo</li>
            </ol>

            <form action="/profile/update" method="post"><label for="bio">Cuéntanos sobre ti:</label>
                <textarea id="bio" name="bio" placeholder="Ingresa tu biografía aquí" aria-label="Biografía del usuario"></textarea>

                <label for="email">Dirección de correo electrónico:</label>
                <input type="email" id="email" name="email" placeholder="[email protected]" aria-label="Dirección de correo electrónico">

                <button type="submit" title="Guardar los cambios de tu perfil">Guardar perfil</button></form>
        </section>

        {# This section is for internal notes and won't be displayed #}
        {% if app.debug %}
        <section class="debug-info">
            <h3>Información de depuración</h3>
            <p>ID de usuario: {{ user.id }}</p>
            <p>Último inicio de sesión: {{ user.lastLogin|date('Y-m-d H:i:s') }}</p>
        </section>
        {% endif %}
    </main>

    <footer>
        <p>¿Necesitas ayuda? <a href="/support" title="Visita nuestro centro de soporte">Contacta con soporte</a></p>
        <p>© {{ "now"|date('Y') }} Nuestra empresa. Todos los derechos reservados.</p>
    </footer>
</body>
</html>

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "twig": {
      "include": ["./[locale]/*.twig"]
    }
  }
}

i18n.lock

version: 1
checksums:
  2d3d028d905803e471ca9f97a4969d5e:
    head/0#content: 1308168cca4fa5d8d7a0cf24e55e93fc
    head/1: 3180ad6b8de344b781637750259e0f53
    body/0/0: 9de5fe40cbf5f851a6d2270f01fe0739
    body/1/0/0: c59070fe496d5e4bd0066295b63a9056
    body/1/0/1: 12d74865332bf1988d51e84ba67aae09
    body/1/0/2: 58f0e438e665c77eedc440c5a8529b1a
    body/1/1/0: 119e3aa396d12a5a1aa7058e0983f9b9
    body/1/1/1/0: 60f9a22f4200bb4620a6ff7a1797ec30
    body/1/1/1/1: 03846a81f16f5e4a11acfd9445ad497d
    body/1/1/1/2: 15aae9d70ff1fb682f7d86baca81dcc0
    body/1/2/0: fbd403146395526d68ac68d142a50e21
    body/1/2/1: da8dc7fe06175d8b805f7f565bfe2788
    body/1/2/2/0: 061e1acc1b9ebad9de09fd5626e813c7
    body/1/2/2/1: 67f022a3f9e278d065a063b5e29dd932
    body/1/2/2/2: 7e23f048179f6661050edaa796528fe0
    body/1/2/3: 635f7e9a4afc00de34f975914afbb8b8
    body/1/3/0: 7a7892379e31868abba9865d20be2b72
    body/1/3/1: 8740df822561d74d51bb30e4b39d6193
    body/1/3/2: 0429f12258fabbde3abaca3dd9986178
    body/2/0: d32e57e4a5a65f3bee8b63dcb2bfa8e7
    body/2/1: 7e10a8ab9cc4e6d603b3cdc48849688f