उपयोगकर्ताओं से पहले अनुपस्थित अनुवादों का पता कैसे लगाएं

एक गायब अनुवाद शायद ही कभी कोई अपवाद फेंकता है। आपके सेटअप के आधार पर यह या तो जापानी उपयोगकर्ता को अंग्रेज़ी स्ट्रिंग दिखाता है, या लाइव पेज पर checkout.summary.total प्रिंट करता है। दोनों शिप हो जाते हैं, दोनों कोड समीक्षा पास कर लेते हैं, और दोनों आपके बजाय ग्राहक द्वारा खोजे जाते हैं।

विषय सूची

यह लागू होता है चाहे आप किसी भी लाइब्रेरी का उपयोग करें

यहाँ कुछ भी किसी एक स्टैक के लिए विशिष्ट नहीं है। नीचे दी गई पहचान परतें i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate या Lingui पर समान रूप से काम करती हैं, क्योंकि वे सभी कुंजियों को एक ही तरह से हल करती हैं और एक ही तरह से विफल होती हैं।

टूलिंग भी पोर्टेबल है। यदि आपके संदेश आज JSON कैटलॉग में रहते हैं, तो Sync JSON प्लगइन Intlayer को उन फ़ाइलों पर इंगित करता है, जिससे आपको अपनी सामग्री को स्थानांतरित किए बिना या एक भी आयात बदले बिना ऑडिट, फिल और टेस्ट कमांड मिलते हैं:

import { syncJSON } from "@intlayer/sync-json-plugin";

const config = {
  plugins: [
    syncJSON({
      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
      format: "i18next", // या next-intl / react-intl के लिए "icu"
    }),
  ],
};

export default config;

यदि आप चाहते हैं कि रनटाइम API भी समान रहे, तो कम्पैट एडॉप्टर बंडलर स्तर पर useTranslation, $t और मित्रों को एलियास करते हैं। किसी भी तरह, नीचे दिए गए आदेशों को विचार के एक कार्यान्वयन के रूप में समझें, आवश्यकता के रूप में नहीं।

वे अदृश्य क्यों हैं

प्रत्येक i18n लाइब्रेरी एक ही श्रृंखला के माध्यम से एक कुंजी को हल करती है: सक्रिय लोकेल देखें, डिफ़ॉल्ट पर वापस जाएं, और यदि वह विफल रहता है, तो कुंजी को ही वापस कर दें। वह अंतिम कदम ही समस्या है। कोई त्रुटि नहीं है, उत्पादन में कोई चेतावनी नहीं है, और कोई असफल परीक्षण नहीं है, क्योंकि पाइपलाइन में कुछ भी गायब कुंजी को असामान्य नहीं मानता है।

फ़ॉलबैक इसे बेहतर बनाने के बजाय बदतर बना देता है। एक पृष्ठ जो चुपचाप अंग्रेज़ी में प्रस्तुत होता है, वह एक अंग्रेज़ी बोलने वाले डेवलपर और आपके पास मौजूद प्रत्येक स्वचालित जांच के लिए ठीक दिखता है। बग केवल उस व्यक्ति को दिखाई देता है जो परिणाम नहीं पढ़ सकता है।

तो सवाल यह नहीं है कि "मैं रनटाइम पर गायब अनुवादों को कैसे संभालूँ"। यह है "मैं गायब अनुवाद को मर्ज करना असंभव कैसे बनाऊं"।

चार स्थान जहाँ आप उन्हें पकड़ सकते हैं

प्रत्येक परत कुछ ऐसा पकड़ती है जो अन्य नहीं पकड़ पाती हैं। आप एक से अधिक चाहते हैं।

अधिकांश टीमों के पास जो अंतर है वह तीसरी पंक्ति है: वे जानते हैं कि उनकी कुंजियाँ मान्य हैं, लेकिन कुछ भी यह जाँच नहीं करता है कि सभी अठारह लोकेल में वास्तव में एक मान है।

परत 1: कुंजी को एक प्रकार बनाएं, स्ट्रिंग नहीं

t("checkout.summry.total") एक टाइपो है जो संकलित होता है। यदि आपकी कुंजियाँ सादी स्ट्रिंग हैं, तो प्रत्येक नाम बदलना एक रनटाइम जोखिम है और प्रत्येक विलोपन एक अनाथ छोड़ देता है।

टाइप की गई कुंजियाँ इसे बिल्ड त्रुटि में बदल देती हैं। react-i18next घोषणा विलय के माध्यम से इसका समर्थन करता है, next-intl आपके संदेश के आकार से अनुमान लगाता है, Lingui स्रोत पाठ से आईडी प्राप्त करता है, और Intlayer घोषणा फ़ाइलों से प्रकार उत्पन्न करता है। वे सभी काम करते हैं; जो भिन्न है वह यह है कि आपको कितना तार लगाना है।

यह परत आवश्यक है और पर्याप्त नहीं है। प्रकार आपके डिफ़ॉल्ट कैटलॉग के आकार का वर्णन करते हैं। वे इस बारे में कुछ नहीं कहते हैं कि क्या कोरियाई में उस कुंजी का कोई मान है।

परत 2: उन स्ट्रिंग्स को लिंट करें जो कभी कुंजियाँ नहीं बनीं

जो अनुवाद आपको नहीं मिल पाता वह अक्सर वह होता है जिसे कभी बाह्य रूप नहीं दिया गया था। किसी घटक में हार्डकोड किया गया लेबल प्रत्येक कैटलॉग-आधारित ऑडिट के लिए अदृश्य होता है, क्योंकि जहाँ तक टूलिंग का संबंध है, स्ट्रिंग मौजूद ही नहीं है।

Intlayer का ESLint प्लगइन इसे no-raw-text के साथ कवर करता है, साथ ही रिवर्स केस के लिए no-unused-content: सामग्री घोषित की गई और अब किसी भी चीज़ द्वारा नहीं पढ़ी गई।

import intlayer from "@intlayer/eslint-plugin";

export default [
  intlayer.configs.recommended,
  {
    rules: {
      "@intlayer/no-raw-text": "error",
      "@intlayer/no-unused-content": "warn",
    },
  },
];

no-unused-content वह है जो कैटलॉग को हमेशा बढ़ने से रोकता है। मृत कुंजियाँ कोई शुद्धता बग नहीं हैं, लेकिन वे वही हैं जो अनुवाद विक्रेता के चालान को आवश्यकता से बड़ा बनाती हैं। ESLint प्लगइन दस्तावेज़ में पूर्ण नियम सूची।

परत 3: ऑडिट लोकेल कवरेज

यह वह परत है जो वास्तविक प्रश्न का उत्तर देती है। Intlayer इसे CLI कमांड के रूप में भेजता है:

npx intlayer content test

यह आपके कॉन्फ़िगर किए गए लोकेल और घोषित शब्दकोशों को पढ़ता है, फिर रिपोर्ट करता है कि कौन सी कुंजियाँ किस लोकेल में और किस फ़ाइल में गायब हैं।

इसे किसी भी चीज़ में जोड़ने से पहले जानने योग्य एक विवरण: CLI एक रिपोर्ट प्रिंट करता है लेकिन विफलता पर गैर-शून्य से बाहर नहीं निकलता है। यदि आप इसे एक लाल बिल्ड की उम्मीद में पाइपलाइन में छोड़ देते हैं, तो आपको टेक्स्ट की एक दीवार के साथ एक हरा बिल्ड मिलेगा जिसे कोई नहीं पढ़ता है। गेटिंग के लिए, इसके बजाय प्रोग्रामेटिक API का उपयोग करें, जिसे नीचे कवर किया गया है।

परत 4: इसे परीक्षण सूट में जोर दें

listMissingTranslations() आपको डेटा के रूप में वही ऑडिट देता है, जो आप बिल्ड गेट के लिए चाहते हैं।

/* @vitest-environment node */
import { listMissingTranslations } from "intlayer/cli";
import { describe, expect, it } from "vitest";

describe("translations", () => {
  it("has no missing required locales", async () => {
    const result = await listMissingTranslations();

    if (result.missingRequiredLocales.length > 0) {
      console.log(result.missingTranslations);
    }

    expect(result.missingRequiredLocales).toHaveLength(0);
  });
});

तीन फ़ील्ड वापस आते हैं, और भेद मायने रखता है:

• missingTranslations: प्रति कुंजी, कौन से लोकेल गायब हैं और किस फ़ाइल से। परीक्षण विफल होने पर आप यही प्रिंट करते हैं।
• missingLocales: प्रत्येक कुंजी में संघ।
• missingRequiredLocales: आपके कॉन्फ़िगरेशन में requiredLocales तक सीमित, या यदि आपने इसे सेट नहीं किया है तो सभी लोकेल।

requiredLocales उपयोगी घुंडी है

अठारह लोकेल शिपिंग का मतलब यह नहीं है कि तैनात करने के लिए सभी अठारह पूर्ण होने चाहिए। अधिकांश टीमों के पास एक स्तर होता है जो रिलीज़ को रोकता है और एक स्तर जो सर्वोत्तम प्रयास होता है।

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.JAPANESE,
      Locales.POLISH,
    ],
    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

requiredLocales के बिना, प्रत्येक घोषित लोकेल की आवश्यकता होती है और आपका बिल्ड तब तक लाल रहता है जब तक कि अंतिम भाषा न आ जाए। आमतौर पर इसी तरह टीमें जांच को पूरी तरह से अक्षम कर देती हैं, जो कि इसे न रखने से भी बदतर है।

उन लोगों को खोजना जो पहले से ही उत्पादन में हैं

ऊपर दी गई परतें नए अंतरालों को रोकती हैं। पहले से शिप किए गए ऐप के लिए, दो चीज़ें मदद करती हैं।

स्यूडोलॉकालाइज़ेशन। एक ऐसा लोकेल चलाएँ जहाँ प्रत्येक स्ट्रिंग बदल दी जाती है, उदाहरण के लिए [!!! Ĉĥéçķöũţ !!!]। सादे अंग्रेज़ी में प्रस्तुत होने वाली कोई भी चीज़ हार्डकोड की जाती है। यह दस मिनट में वह ढूंढ लेता है जो एक कैटलॉग ऑडिट संरचनात्मक रूप से नहीं देख सकता, क्योंकि यह कैटलॉग के बजाय प्रस्तुत पृष्ठ का परीक्षण करता है।

अपनी खुद की साइट क्रॉल करें। यदि आप स्थानीयकृत URL प्रदान करते हैं, तो प्रति लोकेल एक नमूना प्राप्त करें और अपनी डिफ़ॉल्ट-भाषा स्ट्रिंग्स के लिए HTML को ग्रैप करें। /ja/ में "Add to cart" वाला पेज या तो एक गायब अनुवाद है या एक फ़ॉलबैक जिसके बारे में आप नहीं जानते थे।

curl -s https://example.com/ja/checkout | grep -c "Add to cart"

अंतराल को भरना

एक बार जब आप जान जाते हैं कि क्या गायब है, तो intlayer fill खाली प्रविष्टियों को भरता है, और autoFill विकल्प सामग्री घोषित होने पर प्रति-लोकेल फ़ाइलें उत्पन्न कर सकता है। autoFill देखें।

इसके बारे में स्पष्ट होना चाहिए: मशीन से भरे अनुवाद एक दृश्यमान अंतर को एक अदृश्य अंतर में बदल देते हैं। कुंजी का अब एक मान है, इसलिए ऑडिट हरा हो जाता है, और किसी ने शब्दों की समीक्षा नहीं की। रिलीज़ को अनब्लॉक करने के लिए इसका उपयोग करें, फिर ग्राहक द्वारा निर्णय लेने से पहले पढ़ी जाने वाली किसी भी चीज़ के लिए आउटपुट को एक मानव के माध्यम से रूट करें। यह एक पाड़ है, उत्तर नहीं।

सामान्य गलतियाँ

• फ़ॉलबैक को एक सुविधा के रूप में मानना। यह एक रेंडरिंग रणनीति है, सुरक्षा जाल नहीं। एक मूक अंग्रेज़ी पृष्ठ एक ऐसा बग है जो किसी को रिपोर्ट नहीं करता है।
• CI को गेट करने के लिए CLI रिपोर्ट पर भरोसा करना। intlayer content test शून्य से बाहर निकलता है। एक परीक्षण में जोर दें।
• प्रत्येक लोकेल की आवश्यकता। पहली बार जब कोई रिलीज़ आधी-अधूरी भाषा द्वारा अवरुद्ध होती है, तो जांच अक्षम हो जाती है।
• कैटलॉग का ऑडिट करना लेकिन कभी रेंडर किए गए पेज का नहीं। हार्डकोडेड स्ट्रिंग्स परिभाषा के अनुसार कैटलॉग ऑडिट के लिए अदृश्य हैं।
• परीक्षणों में केवल डिफ़ॉल्ट लोकेल की जाँच करना। वह एकमात्र लोकेल जो गायब नहीं हो सकता।
• मशीन फिल को लूप बंद करने देना। हरा ऑडिट, असमीक्षित प्रतिलिपि।

आगे पढ़ें

• अपनी सामग्री का परीक्षण: CLI ऑडिट, प्रोग्रामेटिक API और UI असर्शन
• ESLint प्लगइन नियम, जिनमें no-raw-text और no-unused-content शामिल हैं
• autoFill: प्रति-लोकेल घोषणा फ़ाइलें उत्पन्न करना
• कॉन्फ़िगरेशन संदर्भ: locales, requiredLocales, defaultLocale
• फ्रेमवर्क में बेंचमार्क रिपोर्ट
• ड्रॉप-इन i18next कम्पैट एडॉप्टर
• अंतर्राष्ट्रीयकरण वास्तव में क्या कवर करता है
• प्रति-घटक बनाम केंद्रीकृत i18n