chrome.i18n

คำอธิบาย

ใช้โครงสร้างพื้นฐาน chrome.i18n เพื่อปรับใช้การปรับให้เป็นสากลทั่วทั้งแอปหรือส่วนขยาย

คุณต้องใส่สตริงทั้งหมดที่ผู้ใช้มองเห็นลงในไฟล์ชื่อ messages.json แต่ละครั้ง คุณเพิ่มภาษาใหม่ โดยเพิ่มไฟล์ข้อความภายใต้ไดเรกทอรีชื่อ _locales/_localeCode_ โดยที่ localeCode คือรหัส เช่น en สำหรับภาษาอังกฤษ

นี่คือลำดับชั้นของไฟล์สำหรับส่วนขยายสากลที่รองรับภาษาอังกฤษ (en) สเปน (es) และเกาหลี (ko):

ในไดเรกทอรีส่วนขยาย: ไดเรกทอรี Manifest.json, *.html, *.js, _locales ในไดเรกทอรี _locales: ไดเรกทอรี en, es และ ko แต่ละรายการมีไฟล์ messages.json

วิธีรองรับหลายภาษา

สมมติว่าคุณมีส่วนขยายพร้อมด้วยไฟล์ที่แสดงในรูปต่อไปนี้

ไฟล์ Manifest.json และไฟล์ที่มี JavaScript ไฟล์ .json มี

หากต้องการทำให้ส่วนขยายนี้เป็นสากล คุณต้องตั้งชื่อแต่ละสตริงที่ผู้ใช้มองเห็นได้และใส่ไว้ในข้อความ ไฟล์ Manifest, ไฟล์ CSS และโค้ด JavaScript ของส่วนขยายใช้ชื่อของแต่ละสตริงเพื่อรับ เวอร์ชันแปล

เมื่อส่วนขยายเป็นสากลจะมีลักษณะดังนี้ (โปรดทราบว่าส่วนขยายยังมี สตริงภาษาอังกฤษ):

<img "__msg_extname__",="" "default_locale"="" "th".="" "extname"."="" "สวัสดี="" _locales=&quot;&quot; a=&quot;&quot; alt="ในไฟล์ Manifest.json " and=&quot;&quot; เป็น="" changed=&quot;&quot; chrome.i18n.getmessage("extname")="" defines=&quot;&quot; en=&quot;&quot; file=&quot;&quot; file,=&quot;&quot; has=&quot;&quot; hello=&quot;&quot; in=&quot;&quot; item=&quot;&quot; javascript=&quot;&quot; messages.json=&quot;&quot; named=&quot;&quot; ใหม่="" src=&quot;/static/images/i18n-after-1.gif&quot; the=&quot;&quot; to=&quot;&quot; ค่า="" โลก"="" />

หมายเหตุเกี่ยวกับการทำให้เป็นสากล:

  • คุณจะใช้ภาษาที่รองรับก็ได้ หากคุณใช้ภาษาที่ไม่รองรับ Google Chrome ไม่สนใจ

  • ในไฟล์ manifest.json และ CSS ให้ดูสตริงชื่อ messagename ดังนี้

    __MSG_messagename__

  • ในโค้ด JavaScript ของส่วนขยายหรือแอปพลิเคชันของคุณ ให้ดูที่สตริงชื่อ messagename ดังนี้

    chrome.i18n.getMessage("messagename")

  • ในการเรียก getMessage() แต่ละครั้ง คุณสามารถระบุสตริงได้ถึง 9 สตริงในข้อความ โปรดดู ตัวอย่าง: getMessage สำหรับรายละเอียด

  • ข้อความบางอย่าง เช่น @@bidi_dir และ @@ui_locale มาจากการปรับให้เป็นสากล ระบบ โปรดดูรายการชื่อข้อความที่กำหนดไว้ล่วงหน้าทั้งหมดในส่วนข้อความที่กำหนดไว้ล่วงหน้า

  • ใน messages.json สตริงที่ผู้ใช้มองเห็นแต่ละรายการจะมีชื่อ ซึ่งก็คือ "ข้อความ" ตัวเลือกเพิ่มเติม &quot;description&quot; รายการ ชื่อคือคีย์ เช่น "extName" หรือ "search_string" ซึ่งระบุถึง สตริง "ข้อความ" ระบุค่าของสตริงในภาษานี้ "รายละเอียด" (ไม่บังคับ) ให้ความช่วยเหลือแก่นักแปล ซึ่งอาจจะไม่สามารถดูวิธีการใช้งานสตริงใน ส่วนขยาย เช่น

    {
  "search_string": {
    "message": "hello%20world",
    "description": "The string we search for. Put %20 between words that go together."
  },
  ...
}

    โปรดดูข้อมูลเพิ่มเติมที่รูปแบบ: ข้อความที่ระบุสถานที่

เมื่อส่วนขยายหรือแอปได้รับการทำให้เป็นสากลแล้ว การแปลก็เป็นเรื่องง่าย คุณคัดลอก messages.json แปลเอกสาร และใส่สำเนานั้นในไดเรกทอรีใหม่ภายใต้ _locales เช่น เพื่อสนับสนุน ภาษาสเปน โปรดวางสำเนาที่แปลแล้วของ messages.json ไว้ใต้ _locales/es รูปต่อไปนี้ แสดงส่วนขยายก่อนหน้าพร้อมคำแปลใหม่เป็นภาษาสเปน

ซึ่งดูเหมือนกับรูปก่อนหน้า แต่มีไฟล์ใหม่ที่ _locales/es/messages.json ที่มีการแปลข้อความภาษาสเปน

ข้อความที่กำหนดไว้ล่วงหน้า

ระบบการปรับให้เป็นสากลจะแสดงข้อความที่กำหนดไว้ล่วงหน้าเล็กน้อยเพื่อช่วยคุณแปล เหล่านี้ มี @@ui_locale เพื่อให้คุณสามารถตรวจหาภาษาของ UI ปัจจุบัน และข้อความ @@bidi_... ไม่กี่รายการที่ ให้คุณตรวจจับทิศทางข้อความได้ ข้อความหลังมีชื่อคล้ายกับค่าคงที่ใน แกดเจ็ต BIDI (2 ทิศทาง) API

คุณสามารถใช้ข้อความพิเศษ @@extension_id ในไฟล์ CSS และ JavaScript ไม่ว่าจะเป็น ส่วนขยายหรือแอป ข้อความนี้ใช้ไม่ได้ในไฟล์ Manifest

ตารางต่อไปนี้จะอธิบายข้อความที่กำหนดไว้ล่วงหน้าแต่ละข้อความ

ชื่อข้อความคำอธิบาย
@@extension_idรหัสส่วนขยายหรือรหัสแอป คุณอาจใช้สตริงนี้เพื่อสร้าง URL สำหรับทรัพยากรภายในส่วนขยาย แม้แต่ส่วนขยายที่ไม่ได้แปลก็อาจใช้ข้อความนี้ได้
หมายเหตุ: คุณใช้ข้อความนี้ในไฟล์ Manifest ไม่ได้
@@ui_localeสถานที่ปัจจุบัน คุณอาจใช้สตริงนี้เพื่อสร้าง URL ที่เจาะจงสถานที่
@@bidi_dirทิศทางข้อความของภาษาปัจจุบัน หรือ "ltr" สำหรับภาษาที่อ่านจากซ้ายไปขวา เช่น อังกฤษ หรือ "rtl" สำหรับภาษาที่อ่านจากขวาไปซ้าย เช่น ภาษาญี่ปุ่น
@@bidi_reversed_dirหาก @@bidi_dir เป็น "ltr" ค่าที่ได้จะเป็น "rtl" ไม่เช่นนั้น จะเป็น "ltr"
@@bidi_start_edgeหาก @@bidi_dir เป็น "ltr" จะเป็น "left" ไม่เช่นนั้น ถือว่า "ถูก"
@@bidi_end_edgeหาก @@bidi_dir เป็น "ltr" เท่ากับว่า "ถูกต้อง" ไม่เช่นนั้น จะเป็น "ซ้าย"

ต่อไปนี้คือตัวอย่างการใช้ @@extension_id ในไฟล์ CSS เพื่อสร้าง URL

body {
  background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

หากรหัสส่วนขยายคือ abcdefghijklmnopqrstuvwxyzabcdef บรรทัดตัวหนาในโค้ดก่อนหน้า ข้อมูลโค้ดจะกลายเป็น

  background-image:url('chrome-extension://abcdefghijklmnopqrstuvwxyzabcdef/background.png');

ต่อไปนี้คือตัวอย่างการใช้ข้อความ @@bidi_* ในไฟล์ CSS

body {
  direction: __MSG_@@bidi_dir__;
}

div#header {
  margin-bottom: 1.05em;
  overflow: hidden;
  padding-bottom: 1.5em;
  padding-__MSG_@@bidi_start_edge__: 0;
  padding-__MSG_@@bidi_end_edge__: 1.5em;
  position: relative;
}

สำหรับภาษาที่อ่านจากซ้ายไปขวา เช่น ภาษาอังกฤษ เส้นตัวหนาจะเป็นดังนี้

  dir: ltr;
  padding-left: 0;
  padding-right: 1.5em;

ภาษา

คุณสามารถเลือกจากหลายภาษา รวมถึงบางภาษา (เช่น en) ที่อนุญาตให้แปลภาษาเดียว รองรับภาษาหลายภาษา (เช่น en_GB และ en_US)

ตำแหน่งที่ได้รับการสนับสนุน

คุณสามารถใช้ภาษาที่ Chrome เว็บสโตร์รองรับได้

การค้นหาข้อความ

คุณไม่จำเป็นต้องกำหนดทุกสตริงในทุกภาษาที่รองรับ ตราบใดที่ภาษาเริ่มต้น ไฟล์ messages.json มีค่าสำหรับทุกสตริง ส่วนขยายหรือแอปจะทำงานไม่ว่าอย่างไรก็ตาม คำแปลก็พอประมาณ วิธีที่ระบบส่วนขยายค้นหาข้อความมีดังนี้

  1. ค้นหาไฟล์ข้อความ (หากมี) สำหรับภาษาที่ผู้ใช้ต้องการ ตัวอย่างเช่น เมื่อ Google ภาษาของ Chrome ตั้งค่าเป็นภาษาอังกฤษแบบอังกฤษ (en_GB) ระบบจะมองหาข้อความในภาษาอังกฤษก่อน _locales/en_GB/messages.json หากมีไฟล์นั้นอยู่ และมีข้อความอยู่ในนั้น ระบบจะหา หลังจากนี้
  2. ถ้าภาษาที่ผู้ใช้ต้องการมีภูมิภาค (กล่าวคือ ภาษามีเครื่องหมายขีดล่าง: _) ให้ค้นหา ภาษาที่ไม่มีภูมิภาคนั้น ตัวอย่างเช่น หากไม่มีไฟล์ข้อความ en_GB หรือ ไม่มีข้อความอยู่ ระบบจะหาในไฟล์ข้อความ en หากมีไฟล์นั้นอยู่ และ มีข้อความอยู่ในนั้น ระบบจะไม่หาข้อมูลเพิ่มเติมใดๆ อีก
  3. ค้นหาไฟล์ข้อความสำหรับภาษาเริ่มต้น ตัวอย่างเช่น หากส่วนขยาย "default_locale" ตั้งค่าเป็น "es" และไม่ใช่ _locales/en_GB/messages.json และ _locales/en/messages.json มีข้อความ ส่วนขยายจะใช้ข้อความจาก _locales/es/messages.json

ในรูปต่อไปนี้ ข้อความชื่อว่า "colores" อยู่ในทั้ง 3 ภาษาที่ส่วนขยาย รองรับ แต่ "extName" อยู่ใน 2 ภาษาเท่านั้น ทุกที่ที่ผู้ใช้ใช้ Google Chrome ในสหรัฐอเมริกา ภาษาอังกฤษจะเห็นป้ายกำกับ "สี" ส่วนผู้ใช้ภาษาอังกฤษแบบอังกฤษจะเห็นคำว่า "Colours" ทั้งภาษาอังกฤษแบบสหรัฐอเมริกาและ ผู้ใช้ภาษาอังกฤษแบบอังกฤษจะเห็นชื่อส่วนขยาย " Hello World" เนื่องจากภาษาเริ่มต้นคือภาษาสเปน ผู้ใช้ที่เรียกใช้ Google Chrome ในภาษาอื่นที่ไม่ใช่ภาษาอังกฤษจะเห็นป้ายกำกับ "Colores" และส่วนขยาย ชื่อ "Hola mundo"

4 ไฟล์: Manifest.json และไฟล์ messages.json 3 ไฟล์ (สำหรับ es, en และ en_GB) ไฟล์ es และ en จะแสดงรายการสำหรับข้อความชื่อ

วิธีตั้งค่าภาษาของเบราว์เซอร์

คุณอาจต้องตั้งค่าภาษาของเบราว์เซอร์เพื่อทดสอบการแปล ส่วนนี้จะบอกวิธีตั้ง ภาษาใน Windows, Mac OS X, Linux และ ChromeOS

Windows

คุณสามารถเปลี่ยนภาษาได้โดยใช้ทางลัดเฉพาะภาษาหรือ UI ของ Google Chrome ทางลัดจะรวดเร็วขึ้นเมื่อคุณตั้งค่า และช่วยให้คุณใช้หลายๆ ภาษาพร้อมกันได้

การใช้ทางลัดเฉพาะภาษา

ในการสร้างและใช้ทางลัดที่เปิด Google Chrome ด้วยภาษาเฉพาะ:

  1. ทำสำเนาทางลัดของ Google Chrome ที่มีอยู่บนเดสก์ท็อป
  2. เปลี่ยนชื่อแป้นพิมพ์ลัดใหม่ให้ตรงกับภาษาใหม่

  3. เปลี่ยนคุณสมบัติของทางลัดเพื่อให้ช่อง "เป้าหมาย" ระบุ --lang และ --user-data-dir แฟล็ก เป้าหมายควรมีลักษณะดังนี้

    path_to_chrome.exe --lang=locale --user-data-dir=c:\locale_profile_dir

  4. เปิดใช้งาน Google Chrome โดยดับเบิลคลิกทางลัด

ตัวอย่างเช่น หากต้องการสร้างทางลัดที่เปิด Google Chrome ในภาษาสเปน (es) คุณอาจสร้าง ทางลัดชื่อ chrome-es ที่มีเป้าหมายต่อไปนี้

path_to_chrome.exe --lang=es --user-data-dir=c:\chrome-profile-es

คุณสามารถสร้างทางลัดได้มากเท่าที่ต้องการเพื่อให้การทดสอบในหลายภาษาเป็นเรื่องง่าย สำหรับ ตัวอย่าง:

path_to_chrome.exe --lang=en --user-data-dir=c:\chrome-profile-en
path_to_chrome.exe --lang=en_GB --user-data-dir=c:\chrome-profile-en_GB
path_to_chrome.exe --lang=ko --user-data-dir=c:\chrome-profile-ko
การใช้ UI

วิธีเปลี่ยนการตั้งค่าภาษาโดยใช้ UI บน Google Chrome สำหรับ Windows มีดังนี้

  1. ไอคอนแอป > ตัวเลือก
  2. เลือกแท็บขั้นสูง
  3. เลื่อนลงไปที่เนื้อหาเว็บ
  4. คลิกเปลี่ยนการตั้งค่าแบบอักษรและภาษา
  5. เลือกแท็บ Languages
  6. ใช้เมนูแบบเลื่อนลงเพื่อตั้งค่าภาษาของ Google Chrome
  7. รีสตาร์ท Chrome

Mac OS X

หากต้องการเปลี่ยนภาษาบน Mac คุณต้องใช้ค่ากำหนดของระบบ

  1. จากเมนู Apple ให้เลือกค่ากำหนดของระบบ
  2. ในส่วนส่วนตัว ให้เลือกระหว่างประเทศ
  3. เลือกภาษาและสถานที่ตั้ง
  4. รีสตาร์ท Chrome

Linux

หากต้องการเปลี่ยนภาษาบน Linux ก่อนอื่นให้ปิด Google Chrome จากนั้นให้ตั้งค่า LANGUAGE ตัวแปรสภาพแวดล้อมและเปิดใช้ Google Chrome เช่น

LANGUAGE=es ./chrome

ChromeOS

วิธีเปลี่ยนภาษาใน ChromeOS

  1. จากถาดระบบ ให้เลือกการตั้งค่า
  2. ในส่วนภาษาและการป้อนข้อมูล ให้เลือกเมนูแบบเลื่อนลงภาษา
  3. หากภาษาของคุณไม่อยู่ในรายการ ให้คลิกเพิ่มภาษา แล้วเพิ่มภาษานั้น
  4. เมื่อเพิ่มแล้ว ให้คลิกที่รายการเมนูการทำงานเพิ่มเติม 3 จุดข้างภาษาของคุณ แล้วเลือก แสดง ChromeOS ในภาษานี้
  5. คลิกปุ่มรีสตาร์ทที่ปรากฏถัดจากภาษาที่ตั้งค่าไว้เพื่อรีสตาร์ท ChromeOS

ตัวอย่าง

คุณสามารถดูตัวอย่างง่ายๆ ของการปรับให้เป็นสากลได้ในไดเรกทอรี examples/api/i18n สำหรับ ตัวอย่างที่ครบถ้วน โปรดดู examples/extensions/news สำหรับตัวอย่างอื่นๆ และสำหรับความช่วยเหลือในการดู โปรดดูซอร์สโค้ดในตัวอย่าง

ตัวอย่าง: getMessage

โค้ดต่อไปนี้จะได้รับข้อความที่แปลแล้วจากเบราว์เซอร์ และแสดงเป็นสตริง ทั้งนี้ แทนที่ตัวยึดตำแหน่งสองภายในข้อความด้วยสตริง "string1" และ "string2"

function getMessage() {
  var message = chrome.i18n.getMessage("click_here", ["string1", "string2"]);
  document.getElementById("languageSpan").innerHTML = message;
}

วิธีระบุและใช้สตริงเดียวมีดังนี้

  // In JavaScript code
  status.innerText = chrome.i18n.getMessage("error", errorDetails);

"error": {
  "message": "Error: $details$",
  "description": "Generic error template. Expects error parameter to be passed in.",
  "placeholders": {
    "details": {
      "content": "$1",
      "example": "Failed to fetch RSS feed."
    }
  }
}

โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับตัวยึดตำแหน่งในหน้าข้อความที่เจาะจงภาษา สำหรับรายละเอียดเกี่ยวกับ การเรียก getMessage() โปรดดูการอ้างอิง API

ตัวอย่าง: getacceptLanguages

โค้ดต่อไปนี้จะรับภาษาที่ยอมรับจากเบราว์เซอร์ และแสดงเป็นสตริงโดย คั่นแต่ละภาษายอมรับด้วย ","

function getAcceptLanguages() {
  chrome.i18n.getAcceptLanguages(function(languageList) {
    var languages = languageList.join(",");
    document.getElementById("languageSpan").innerHTML = languages;
  })
}

โปรดดูรายละเอียดเกี่ยวกับการโทร getAcceptLanguages() ที่ข้อมูลอ้างอิง API

ตัวอย่าง: detectLanguage

โค้ดต่อไปนี้ตรวจหาภาษาสูงสุด 3 ภาษาจากสตริงที่ระบุ และแสดงผลลัพธ์เป็น คั่นด้วยการขึ้นบรรทัดใหม่

function detectLanguage(inputText) {
  chrome.i18n.detectLanguage(inputText, function(result) {
    var outputLang = "Detected Language: ";
    var outputPercent = "Language Percentage: ";
    for(i = 0; i < result.languages.length; i++) {
      outputLang += result.languages[i].language + " ";
      outputPercent +=result.languages[i].percentage + " ";
    }
    document.getElementById("languageSpan").innerHTML = outputLang + "\n" + outputPercent + "\nReliable: " + result.isReliable;
  });
}

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการโทร detectLanguage(inputText) โปรดดูที่ข้อมูลอ้างอิง API

ประเภท

LanguageCode

Chrome 47 ขึ้นไป

รหัสภาษา ISO เช่น en หรือ fr ดูรายการภาษาที่วิธีการนี้รองรับได้ที่ kLanguageInfoTable สำหรับภาษาที่ไม่รู้จัก ระบบจะแสดงผล und ซึ่งหมายความว่า CLD ไม่รู้จักข้อความ [percentage]

ประเภท

สตริง

เมธอด

detectLanguage()

สัญญา Chrome 47 ขึ้นไป 
chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

ตรวจหาภาษาของข้อความที่ให้ไว้โดยใช้ CLD

พารามิเตอร์

  • ข้อความ

    สตริง

    สตริงอินพุตของผู้ใช้ที่จะแปล

  • Callback

    ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (result: object) => void

    • ผลลัพธ์

      ออบเจ็กต์

      ออบเจ็กต์ LanguageDetectionResult ที่เก็บค่าความเชื่อถือได้ของภาษาและอาร์เรย์ของ DetectedLanguage

      • isReliable

        boolean

        CLD ตรวจพบความน่าเชื่อถือของภาษา

      • ภาษา

        object[]

        อาร์เรย์ของที่ตรวจพบLanguage

        • ภาษา

          สตริง

        • เปอร์เซ็นต์

          ตัวเลข

          เปอร์เซ็นต์ของภาษาที่ตรวจพบ

การคืนสินค้า

  • Promise&lt;object&gt;

    Chrome 99 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getAcceptLanguages()

สัญญา 
chrome.i18n.getAcceptLanguages(
  callback?: function,
)

รับภาษาที่ยอมรับของเบราว์เซอร์ ซึ่งแตกต่างจากภาษาที่เบราว์เซอร์ใช้ ในการค้นหาภาษา ให้ใช้ i18n.getUILanguage

พารามิเตอร์

  • Callback

    ไม่บังคับ

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (languages: string[]) => void

    • ภาษา

      สตริง[]

      อาร์เรย์ของ LanguageCode

การคืนสินค้า

  • Promise&lt;LanguageCode[]&gt;

    Chrome 99 ขึ้นไป

    Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

getMessage()

chrome.i18n.getMessage(
  messageName: string,
  substitutions?: any,
  options?: object,
)

รับสตริงที่แปลแล้วสำหรับข้อความที่ระบุ หากไม่มีข้อความ เมธอดนี้จะแสดงสตริงว่างเปล่า ('') หากรูปแบบของการเรียก getMessage() ไม่ถูกต้อง ตัวอย่างเช่น messageName ไม่ใช่สตริง หรืออาร์เรย์ การแทนที่ มีองค์ประกอบมากกว่า 9 รายการ วิธีนี้แสดงผล undefined

พารามิเตอร์

  • messageName

    สตริง

    ชื่อข้อความตามที่ระบุไว้ในไฟล์ messages.json

  • การใช้แทน

    ใดก็ได้ไม่บังคับ

    สตริงทดแทนสูงสุด 9 สตริง หากข้อความต้องการสตริงใด

  • ตัวเลือก

    ออบเจ็กต์ไม่บังคับ

    Chrome 79 ขึ้นไป
    • escapeLt

      บูลีน ไม่บังคับ

      Escape < ในการแปลเป็น &lt; ซึ่งจะมีผลกับข้อความเท่านั้น ไม่ใช่ตัวยึดตำแหน่ง นักพัฒนาซอฟต์แวร์อาจต้องการใช้คำแปลนี้หากใช้คำแปลในบริบท HTML เทมเพลตการปิดที่ใช้กับคอมไพเลอร์ Closure จะสร้างเทมเพลตนี้โดยอัตโนมัติ

การคืนสินค้า

  • สตริง

    ข้อความได้รับการแปลสำหรับภาษาปัจจุบัน

getUILanguage()

chrome.i18n.getUILanguage()

รับภาษา UI เบราว์เซอร์ของเบราว์เซอร์ ซึ่งแตกต่างจาก i18n.getAcceptLanguages ซึ่งแสดงภาษาของผู้ใช้ที่ต้องการ

การคืนสินค้า

  • สตริง

    รหัสภาษา UI ของเบราว์เซอร์ เช่น en-US หรือ fr-FR