chrome.i18n

คำอธิบาย

ไฟล์ Manifest

หากส่วนขยายมีไดเรกทอรี /_locales ไฟล์ Manifest ต้องกำหนด "default_locale"

แนวคิดและการใช้งาน

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

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

รองรับหลายภาษา

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

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

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

หมายเหตุเกี่ยวกับการปรับให้เหมาะกับผู้ใช้ทั่วโลกมีดังนี้

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

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

  __MSG_messagename__
  

• ในโค้ด JavaScript ของส่วนขยายหรือแอป ให้อ้างอิงสตริงชื่อ messagename ดังนี้

  chrome.i18n.getMessage("messagename")
  

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

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

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

  {
    "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 รูปภาพต่อไปนี้แสดงส่วนขยายเวอร์ชันเก่าที่มีการแปลภาษาสเปนใหม่

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

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

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

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

ตัวอย่างการใช้ @@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 เว็บสโตร์รองรับ หากภาษาของคุณไม่อยู่ในรายการนี้ ให้เลือกภาษาอื่นที่ใกล้เคียงที่สุด เช่น หากภาษาเริ่มต้นของส่วนขยายคือ "de_CH" ให้เลือก "de" ใน 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 ในสหรัฐอเมริกาที่ใช้ภาษาอังกฤษเห็นป้ายกำกับ "สี" ผู้ใช้ภาษาอังกฤษแบบบริติชจะเห็น "สี" ทั้งผู้ใช้ภาษาอังกฤษแบบสหรัฐอเมริกาและอังกฤษจะเห็นชื่อส่วนขยายว่า "Hello World" เนื่องจากภาษาเริ่มต้นคือสเปน ผู้ใช้ที่ใช้ Google Chrome ในภาษาที่ไม่ใช่ภาษาอังกฤษจะเห็นป้ายกำกับ "Colores" และชื่อส่วนขยาย "Hola mundo"

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

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

Windows

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

ใช้แป้นพิมพ์ลัดเฉพาะภาษา

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

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

3. เปลี่ยนพร็อพเพอร์ตี้ของแป้นพิมพ์ลัดเพื่อให้ช่องเป้าหมายระบุ Flag --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. เลือกแท็บภาษา
6. ใช้เมนูแบบเลื่อนลงเพื่อตั้งค่าภาษาของ Google Chrome
7. รีสตาร์ท Chrome

Mac OS

หากต้องการเปลี่ยนภาษาใน 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()

โค้ดต่อไปนี้จะรับข้อความที่แปลแล้วจากเบราว์เซอร์และแสดงเป็นสตริง โดยแทนที่ตัวยึดตําแหน่ง 2 ตัวในข้อความด้วยสตริง "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()

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

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

chrome.i18n.detectLanguage(
  text: string,
  callback?: function,
)

chrome.i18n.getAcceptLanguages(
  callback?: function,
)

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

chrome.i18n.getUILanguage()