若要在 Mac 上驗證翻譯的佔位符，請將每個引數的位置、類型和預期用途與原始訊息進行比較。使用 Xcode 的不匹配診斷，然後檢查複數替換，並使用不同的範例值測試呈現的標籤。

本指南適用於在 Xcode 中審查 Mac 應用程式本地化標籤的人員。任務是將一條訊息及其翻譯與應用程式提供的值進行核對。下方所有標籤均為合成英文範例；它們說明格式機制，而非實際翻譯。

什麼屬於訊息的引數合約？

引數合約是一份審查記錄，描述訊息接收的值：它們的位置、格式類型、含義和預期用途。它是從原始碼和目錄衍生出的實用檢查清單，而非獨立的 Apple 檔案格式。

Swift 的 String.LocalizationValue 支援帶有插值執行階段值的可本地化字串。其文件也區分了使用原始文字作為本地化鍵，與提供單獨的鍵和預設值。因此，單靠識別碼可能無法揭示訊息的引數：請檢查預設原始文字及其呼叫點。 String.LocalizationValue

考慮格式字串 Added %lld items to %@。在這個說明中，應用程式提供一個整數計數，後面跟著一個物件支援的集合標籤。在編輯翻譯前先寫下合約：

引數位置 含義 預期格式 說明值
1 新增項目數量 %lld 7
2 目的地集合標籤 %@ Canvas

Apple 的格式參考將 %@ 定義為物件轉換，%d 為有號 32 位整數，%f 為雙精度轉換，而 ll 為 long long 的整數長度修飾符。它也記錄了位置形式，例如 %1$@。請保留完整的類型資訊；將 %lld 改為 %d 會改變預期的整數類型。該參考已封存，因此請將其作為格式語法參考，並搭配當前的目錄文件使用。 String Format Specifiers

即使引數類型相同，也要將引數的含義加入審查記錄。對於 Moved %@ to %@，類型檢查無法區分項目標籤和目的地標籤。正確的語法仍然需要值與文字之間的正確關係。

如何在 Xcode 中找到權威來源？

從在 Xcode 中打開專案開始，並識別包含該訊息的目錄。如果原始碼已變更，請選擇 Product > Build 以重新整理提取的字串。在專案導覽器中選擇目錄，選擇 Editor > Assistant，然後選擇訊息鍵以查看其原始碼。Apple 有文件記錄此工作流程，用於定位和更新目錄項目。 Localizing and varying text with a string catalog

檢查呼叫點實際提供哪些值、順序為何，以及透過哪個本地化 API。Apple 建議使用可本地化的 API，例如 String(localized:)；具有單獨 defaultValue 的初始化器會將其第一個參數作為鍵，第二個作為預設原始字串。當中性識別碼（例如 collection.added.summary）擁有該訊息時，這點很重要。 Preparing your app’s text for translation

將三項內容一起記錄：目錄和鍵、預設原始措辭、以及有序的引數含義和類型。如果這些不一致，請在調整翻譯前先解決分歧。否則，您可能會讓翻譯符合過時的原始碼，而不是應用程式當前的輸入。

也為未來的編輯提供背景資訊。Apple 支援在可本地化字串上添加註解以解釋其用途。一個有用的合成註解會說明引數 1 是項目計數，引數 2 是目的地集合標籤。這能給本地化人員提供格式指定符無法表達的資訊。 Preparing your app’s text for translation

如何檢查計數、類型和引數位置？

Apple 引入了字串目錄驗證，用於常見問題，包括不匹配的格式指定符，並提供部分問題的修正。檢查 Xcode 為該項目呈現的任何診斷。將提供的修正視為提議的語法修復，並驗證其是否保留了訊息的含義。 Build multilingual-ready apps

對於不含複數替換的簡單訊息，請使用此審查序列：

  1. 識別原始文字和候選文字中每個消耗引數的佔位符。
  2. 將每個佔位符分配到其引數位置。
  3. 將其完整格式類型與合約比較。
  4. 檢查每個必要值是否出現在措辭預期的位置。
  5. 分別調查新增、省略或重複的引用。

位置標記法讓翻譯可以改變語序，同時保留引數身分。在 %2$@: added %1$lld items 中，第一個可見佔位符引用引數 2，第二個引用引數 1。Apple 有文件記錄 n$ 位置語法。 String Format Specifiers

下表決策表適用於上述說明性的雙引數合約。這些是建議的審查結果，而非執行 Xcode 的結果：

候選格式文字 審查結果 理由
Added %lld items to %@ 符合簡單合約 計數在前，目的地在後
%2$@: added %1$lld items 重新排序後符合 明確位置保留兩個引數身分
Added %d items to %@ 修正整數類型 引數 1 不再使用預期的長度修飾符
Added %lld items 調查省略 此訊息所需的目的地缺失
Added %1$lld items to %1$@ 修正引用 引數 1 以衝突類型被引用；引數 2 缺失
Added %1$lld items to %2$@ (%2$@) 檢查重複 有三次出現但只有兩個不同的被引用引數

將出現次數與不同引數計數分開。最後一行故意示範差異：重複引數 2 不會產生第三個提供的值。該重複是否屬於措辭屬於編輯決策。對於此任務，請標記它，直到其目的確立為止。

同理，不要將每個百分號字元都視為引數。Apple 將 %% 定義為字面百分號。像 Scale: %lld%% 這樣的格式標籤包含一個值佔位符和一個跳脫百分號。 String Format Specifiers

為何複數替換需要不同的檢查？

複數訊息需要審查選擇機制以及顯示值的文字。在其字串目錄工作階段中，Apple 解釋替換可以包含複數情況的字典。檢查器會顯示控制引數的位置和 C 風格格式指定符。因此，即使特定分支不以數值形式列印該引數，替換仍可能依賴該引數。 Discover String Catalogs

對於合成項目計數訊息，比較 One item added 和 %lld items added。第一個分支拼寫出數量；第二個列印數量。要求每個分支都有相同可見佔位符計數的規則會不必要地拒絕第一個分支。Apple 文件記錄的字串字典行為明確允許從複數形式中省略數值格式指定符，並提供拼寫數字作為選項。 Stringsdict file format

改用這種感知分支的審查：

  • 在檢查器中驗證替換的控制引數位置和類型。
  • 檢查目標本地化中存在的每個複數分支。
  • 將每個顯示的佔位符與其引用的引數核對。
  • 透過分支措辭解釋任何省略的數值顯示。
  • 分開檢查其他訊息引數；拼寫計數並不能解釋缺失的集合標籤。

對於兩個獨立變化的計數，保留它們各自的角色。關於項目和集合的合成訊息需要項目計數控制項目替換，集合計數控制集合替換。Apple 文件記錄了一條訊息中的多重替換，並解釋執行階段輸出會結合它們選擇的複數情況。 Discover String Catalogs

如何在 Mac 上確認修正後的訊息？

修復項目後，建置應用程式並檢查任何剩餘的目錄診斷。然後在目標本地化中執行相關畫面。Apple 支援的工作流程是選擇 Product > Scheme > Edit Scheme，選擇 Run，開啟 Options，選擇 App Language 和適當的 App Region，點擊 Close，然後執行選定的目的地。 Testing localizations when running your app

選擇能讓交換可見的範例值。對於兩個計數引數，使用不同的數字，例如 2 和 7。對於兩個文字引數，使用不同的標籤，例如 Tile 和 Canvas。這些是說明性的測試輸入：其目的是揭示每個提供的值出現在訊息的哪一部分。

對於複數化訊息，測試能觸及待審查分支的值。當兩個替換獨立變化時，包含改變一個計數而保持另一個固定的組合。檢查所選措辭和每個顯示值的位置。一個組合成功呈現並不代表其他分支已被檢查。

將翻譯狀態與您的合約檢查分開。Apple 將目錄的綠色核取標記描述為輸入文字後的已翻譯狀態。記錄您實際執行的檢查——引數對應、類型比較、分支檢查和呈現範例——而不要將該狀態指示視為所有四項的證據。 Localizing and varying text with a string catalog

當佔位符解析為預期的提供引數、其類型匹配、且任何特定分支的省略或重複都有明確解釋時，訊息即可推進。將該簡潔合約置於訊息旁，會讓下一次原始碼或翻譯編輯更容易評估。

來源