Next.js + PolyLingo

چندزبانه کردن اپلیکیشن Next.js شما.

فایل‌های محلی، محتوای Markdown و صفحات HTML خود را از طریق یک فراخوانی API واحد ترجمه کنید. با App Router، next-intl و هر تنظیم i18n دیگری کار می‌کند.

App Router
پشتیبانی شده در Next.js 13–15
next-intl
ادغام بومی
10 زبان
یک بار اجرای اسکریپت
~3s
زمان اجرای معمول اسکریپت ترجمه

Next.js مسیریابی را به شما می‌دهد. ترجمه‌ها را نمی‌دهد.

Next.js App Router پشتیبانی داخلی عالی برای مسیریابی مبتنی بر زبان دارد. کتابخانه‌هایی مانند next-intl مدیریت فایل‌های ترجمه و تغییر زبان را ساده می‌کنند. اما آن‌ها خود ترجمه را حل نمی‌کنند — کسی باید محتوای ترجمه شده را به هر زبان تولید کند و آن شخص معمولاً شما هستید. برای اکثر تیم‌ها، روند کار این است که JSON انگلیسی را در DeepL کپی کنند، قالب‌بندی خراب شده را اصلاح کنند، نتیجه را جای‌گذاری کنند و برای هر زبان تکرار کنند. این روند کند، پرخطا و غیرقابل توسعه است.

رایج‌ترین روند کار این است که همه رشته‌های UI را به انگلیسی در کد منبع بنویسید، سپس فایل messages.json را برای هر زبان هدف ترجمه کنید. از نظر تئوری این ساده است. اما در عمل، همگام نگه داشتن بیش از ۱۰ فایل locale با تغییرات منبع به یک مشکل مکرر تبدیل می‌شود. هر بار که متن انگلیسی تغییر می‌کند، همه فایل‌های locale باید به‌روزرسانی شوند. هنگام استفاده از APIهای ترجمه استاندارد، نام کلیدها خراب می‌شود، جایگزین‌های متغیر ترجمه می‌شوند و ساختار JSON بین localeها تغییر می‌کند — که باعث بروز باگ‌های ظریف در زمان اجرا می‌شود که ردیابی آن‌ها دشوار است.

PolyLingo در تنظیمات i18n موجود Next.js شما جای می‌گیرد.

اگر از next-intl یا هر کتابخانه i18n دیگری استفاده می‌کنید، پیام‌های شما قبلاً در JSON هستند. PolyLingo آن JSON را می‌گیرد، از طریق مدل ترجمه می‌فرستد و نسخه‌های ترجمه شده برای هر زبان هدف را بازمی‌گرداند — با کلیدها دست‌نخورده، ساختار تو در تو حفظ شده و مقادیر رشته‌ای به درستی ترجمه شده. می‌توانید آن را از اسکریپت ساخت، وبهوک یا رابط کاربری PolyLingo فراخوانی کنید. نتیجه مستقیماً در دایرکتوری پیام‌های شما قرار می‌گیرد.

روند کار: پیام‌های انگلیسی خود را در messages.json بنویسید. یک اسکریپت واحد اجرا کنید که API PolyLingo را با فایل منبع و همه کدهای زبان هدف فراخوانی می‌کند. یک فایل JSON ترجمه شده برای هر زبان با ساختار یکسان دریافت کنید. هر کدام را در دایرکتوری messages/ خود بنویسید. کامیت کنید. تمام.

برای سایت‌های محتوایی سنگین با Markdown در CMS (Sanity، Contentful)، همین روش برای محتوا اعمال می‌شود: خروجی به صورت Markdown یا HTML، ترجمه، بازنویسی به CMS از طریق API آن. کل خط لوله می‌تواند به عنوان یک مرحله ساخت یا با فعال شدن وبهوک اجرا شود.

اسکریپت ترجمه PolyLingo — این مخزن translate-messages.mjs را ارائه می‌دهد
// This repository: frontend/scripts/translate-messages.mjs
// Chunks large namespaces (e.g. home) so the model stays within output limits.
//
//   export POLYLINGO_API_KEY=pl_xxx
//   npm run i18n:polylingo
//
// Writes messages/es.json, fr.json, … from messages/en.json via POST /v1/translate
// with format: "json". See MARKETING_I18N.md for options and CI notes.
//
// Minimal one-shot pattern (fine for small message files):
//
// const source = readFileSync('./messages/en.json', 'utf8')
// const { translations } = await fetch(apiUrl + '/translate', {
//   method: 'POST',
//   headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
//   body: JSON.stringify({
//     content: source, format: 'json', source: 'en',
//     targets: ['es', 'fr', 'de'], model: 'standard',
//   }),
// }).then((r) => r.json())
//
// for (const [lang, raw] of Object.entries(translations)) {
//   const obj = typeof raw === 'string' ? JSON.parse(raw) : raw
//   writeFileSync(`./messages/${lang}.json`, JSON.stringify(obj, null, 2))
// }
i18n.ts — پیکربندی next-intl نسخه ۴
// i18n.ts (next-intl v4)
import { getRequestConfig } from 'next-intl/server'

export const locales = [
  'en', 'ar', 'bn', 'cs', 'da', 'de', 'el', 'es', 'fa', 'fi',
  'fr', 'he', 'hi', 'id', 'it', 'ja', 'ko', 'ms', 'nl', 'no',
  'pl', 'pt', 'ru', 'sv', 'sw', 'th', 'tr', 'uk', 'vi', 'zh',
] as const
export type Locale = (typeof locales)[number]

export default getRequestConfig(async ({ requestLocale }) => {
  const locale = await requestLocale
  return {
    locale,
    messages: (await import(`./messages/${locale}.json`)).default,
  }
})
package.json — افزودن ترجمه به خط لوله ساخت شما
// package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "i18n:polylingo": "node scripts/translate-messages.mjs",
    "translate:build": "npm run i18n:polylingo && next build"
  }
}

چرا PolyLingo با روند کاری i18n در Next.js سازگار است

  • ترجمه مستقیم فایل‌های messages/*.json — کلیدها همیشه حفظ می‌شوند
  • ترجمه محتوای Markdown برای پست‌های وبلاگ و صفحات مستندات
  • کار با next-intl، next-i18next و تنظیمات سفارشی
  • API REST با اسکریپت‌های ساخت و وبهوک‌های CMS ادغام می‌شود
  • تمام ۳۶ زبان در یک درخواست واحد
  • سطح رایگان — ۱۰۰٬۰۰۰ توکن در ماه
  • این مخزن روند کار را خود استفاده می‌کند: npm run i18n:polylingo فایل‌های محلی بازاریابی را از messages/en.json بازتولید می‌کند (رجوع کنید به MARKETING_I18N.md).
  • کار با App Router و Pages Router
  • فایل‌های خروجی آماده کامیت هستند — نیازی به قالب‌بندی مجدد نیست

چندزبانه کردن اپلیکیشن Next.js خود را راه‌اندازی کنید

1

next-intl را با فایل پیام‌های انگلیسی خود راه‌اندازی کنید

next-intl را نصب و i18n.ts و middleware خود را پیکربندی کنید. همه رشته‌های UI را در messages/en.json بنویسید. فایل را هر طور که اپ شما نیاز دارد ساختاربندی کنید — تخت یا تو در تو. این منبع حقیقت واحد شما خواهد بود.

2

اسکریپت ترجمه را اجرا کنید

از API JSON PolyLingo در یک اسکریپت کوچک Node استفاده کنید (کد بالا را ببینید). در این مونورپو، از frontend/ دستور npm run i18n:polylingo را با تنظیم POLYLINGO_API_KEY اجرا کنید — این اسکریپت فضاهای نام بزرگ را برای اطمینان به بخش‌های کوچک تقسیم می‌کند. اجرای معمولی برای یک بسته کامل بازاریابی کمتر از یک دقیقه طول می‌کشد.

3

فایل‌های locale را کامیت و منتشر کنید

فایل‌های locale تولید شده JSON معتبری با ساختار یکسان با منبع شما هستند. آن‌ها را در مخزن خود کامیت کنید. اسکریپت ترجمه را به خط لوله CI خود اضافه کنید تا localeها با هر تغییر محتوا همگام بمانند.

موارد استفاده چندزبانه در Next.js

🚀

اپلیکیشن‌ها و داشبوردهای SaaS

کل کتابخانه رشته‌های UI خود را در یک اجرای اسکریپت ترجمه کنید. از همه ویژگی‌های قالب‌بندی next-intl پشتیبانی می‌کند — تاریخ‌ها، اعداد، جمع‌ها — زیرا ساختار JSON دقیقاً حفظ می‌شود.

📰

سایت‌های محتوا و وبلاگ‌ها

برای سایت‌های Next.js با محتوای سنگین که از Sanity یا Contentful استفاده می‌کنند، از PolyLingo برای ترجمه محتوای صفحات و رشته‌های UI استفاده کنید — همان API، همان تضمین حفظ قالب.

🛒

تجارت الکترونیک با نسخه‌های منطقه‌ای

نام محصولات، توضیحات، صفحات دسته‌بندی و UI پرداخت را ترجمه کنید. برای متن‌های بازاریابی که صدای برند اهمیت دارد از مدل پیشرفته و برای رشته‌های UI کاربردی از مدل استاندارد استفاده کنید.

سؤالات متداول

آیا این با Next.js App Router کار می‌کند؟

بله. ادغام PolyLingo فقط یک اسکریپت است که فایل‌های JSON را می‌خواند و می‌نویسد — وابستگی به بخش‌های داخلی Next.js ندارد. با App Router، Pages Router یا هر فریم‌ورک دیگری کار می‌کند. مثال پیکربندی next-intl نشان داده شده از API نسخه ۴ با requestLocale استفاده می‌کند که با Next.js 13، 14 و 15 سازگار است.

اگر messages.json من اغلب تغییر کند چه؟

الگوی پیشنهادی این است که اسکریپت ترجمه را به خط لوله CI/CD خود اضافه کنید که هنگام تغییر در messages/en.json فعال شود. این باعث می‌شود همه فایل‌های locale به طور خودکار همگام بمانند. برای تیم‌هایی که تغییرات متنی مکرر دارند، این کاملاً از انحراف locale جلوگیری می‌کند.

آیا PolyLingo با next-i18next و next-intl کار می‌کند؟

بله. next-i18next از همان ساختار JSON locale استفاده می‌کند. اسکریپت ترجمه به همان شکل کار می‌کند — آن را به دایرکتوری public/locales/en/ خود اشاره دهید و خروجی‌ها را به دایرکتوری‌های locale دیگر بنویسید. سازگاری فرمت JSON یکسان است.

محتوای پویا که در فایل پیام‌ها نیست چه؟

محتوای پویا — پست‌های وبلاگ، توضیحات محصول، محتوای تولید شده توسط کاربر — باید در لایه داده ترجمه شود، یا در CMS شما یا از طریق اسکریپت ساخت که محتوا را قبل از رسیدن به Next.js پردازش می‌کند. PolyLingo برای این منظور Markdown، HTML و متن ساده را به یک اندازه خوب پشتیبانی می‌کند.

آیا می‌توان فقط رشته‌هایی که از آخرین اجرا تغییر کرده‌اند را ترجمه کرد؟

ترجمه افزایشی (فقط ترجمه کلیدهای تغییر یافته) در برنامه راه است. در حال حاضر اسکریپت کل فایل را دوباره ترجمه می‌کند. برای اکثر فایل‌های پیام (کمتر از ۲۰ کیلوبایت)، این به اندازه کافی سریع است که در هر کامیت اجرا شود. برای فایل‌های بسیار بزرگ، تقسیم بر فضای نام روش توصیه شده است.

آیا راهی برای بازبینی ترجمه‌ها قبل از انتشار وجود دارد؟

الگوی پیشنهادی این است که فایل‌های locale ترجمه شده را در یک شاخه یا PR جداگانه برای بازبینی قبل از ادغام به شاخه اصلی کامیت کنید. این روش استاندارد برای تیم‌هایی است که نیاز به بازبینی انسانی کیفیت ترجمه دارند. PolyLingo یک پیش‌نویس خوب تولید می‌کند — برای اکثر رشته‌های UI خروجی مدل استاندارد نیازی به ویرایش ندارد.

اولین فایل محلی خود را در کمتر از ۵ دقیقه ترجمه کنید.

کلید API رایگان. بدون کارت اعتباری. JSON پیام‌های خود را جای‌گذاری کنید و خروجی را فوراً ببینید.

کلید API خود را دریافت کنید

راه‌اندازی اسکریپت ترجمه ۵ دقیقه طول می‌کشد. سطح رایگان — نیازی به کارت اعتباری نیست.

چندزبانه کردن اپلیکیشن Next.js شما — PolyLingo | PolyLingo