重新命名字串目錄索引鍵，同時保留訊息與翻譯

若要在 Xcode 中重新命名字串目錄索引鍵，請另外保留來源訊息、更新程式碼中的參照，並確認所有現有翻譯與變體都完整保留。對於擷取出的字串，Xcode 26 提供轉換重構；只變更查找索引鍵並不足夠。

本指南適用於維護既有 .xcstrings 目錄的 SwiftUI Mac app 開發者。目標是在保留顯示文字與翻譯的同時，將以訊息文字為主的索引鍵改為有意義的識別碼。Apple 說明了下文所述的 API 與轉換流程，但並未保證任意修改索引鍵都會自動轉移每一項翻譯。

變更索引鍵時，哪些內容必須保持不變？

可本地化訊息不只有識別碼。Apple 將索引鍵、預設值、註解與字串表描述為不同的組成部分。索引鍵用於執行階段識別訊息；預設值提供來源文字。目錄則保存字串表的翻譯與中繼資料。請將重新命名視為對該訊息契約所做的協調變更。探索字串目錄

編輯前，請為每個受影響的項目記錄下列資訊。這些虛構範例用來說明重新命名，並非實測結果。

組成部分	變更前	預期結果
查找索引鍵	Open collection	collection.open
來源訊息	Open collection	不變
字串表	Localizable	不變
套件	主 app 套件	不變
翻譯者語境	開啟所選集合的按鈕	保留
現有翻譯	各語言版本的目前值	保留
計數引數（若有）	整數計數	型別與意義相同
複數或裝置變體	現有分支	保留

將這份記錄作為比對依據。成功建置本身無法證明翻譯仍然存在：查找失敗時，app 仍可能顯示預設訊息。SwiftUI 文件指出，若找不到目錄項目，本地化索引鍵可能會直接顯示。使用語意化索引鍵時，介面上可能因此出現 collection.open 之類的識別碼。讓檢視準備好進行本地化

編輯目錄前先找到來源

在 Xcode 的「專案」導覽器中開啟既有目錄。選擇 Editor > Assistant，再選取項目以檢視其來源。Apple 也說明，可以使用索引鍵旁的箭頭，以及「屬性檢閱器」中的範例用法來尋找參照。若是擷取出的字串，請在變更來源後選擇 Product > Build，以同步目錄。使用字串目錄本地化文字並設定變體

確認該項目是從程式碼擷取，還是手動管理。Apple 說明，擷取出的訊息由原始碼控制：建置時會同步其來源值。已翻譯但不再被擷取的項目會標記為 Stale；未翻譯的項目則可能遭到移除。手動管理的項目不會因擷取而更新或移除。因此，請勿只因為新項目已出現，就刪除舊的已翻譯項目。探索字串目錄

繼續之前先建立可還原的檢查點，之後再將受影響的項目與檢查點比對。這項作業期間請保持字串表與套件不變，減少翻譯遺失的可能原因。Apple 的本地化 API 接受字串表與套件資訊，正是因為這些資訊會決定訊息的查找位置。準備 app 文字以供翻譯

對擷取出的字串使用 Xcode 轉換重構

若專案使用 Xcode 26 或以上版本，可考慮將現有的擷取項目轉換為產生的本地化符號。Apple 在 Xcode 26 引入此工作流程，並示範如何在轉換期間將索引鍵改為語意化名稱。這是有文件說明的途徑，可同時變更訊息的識別方式與參照方式。跟著操作：使用 Xcode 探索本地化

1. 在建置設定中，確認 Generate String Catalog Symbols 是否設為 Yes；若既有專案需要，請啟用此設定。
2. 在目錄編輯器中選取現有索引鍵，按住 Control 鍵並按一下，然後選擇 Refactor > Convert Strings to Symbols。
3. 檢查預覽，確認目錄索引鍵的變更及受影響的來源位置。
4. 在轉換介面中編輯建議的語意化名稱，以及適用時的引數名稱。
5. 使用醒目提示的預覽比對目前與修改後的程式碼，然後按一下 Convert。
6. 建置，並將產生的項目與檢查點比對，包括翻譯與變體。

Apple 有說明這些轉換控制項，並在「屬性檢閱器」中展示產生的用法範例。請參照這些範例，不要依據預定目錄索引鍵中的標點自行猜測 Swift 識別碼。產生的符號取決於目錄資訊；若使用非預設字串表，符號也會帶有字串表命名空間。在程式碼中使用產生的本地化符號

這項重構專門用於將擷取出的字串轉為產生的符號。引用的文件並未證明所有手動管理項目或外部參照都能透過通用重新命名操作完成變更。如果預覽未包含必要參照，請先明確處理，再移除舊索引鍵。

若偏好在程式碼中保留索引鍵與預設值，請繼續使用擷取

你也可以繼續使用由程式碼驅動的擷取方式。Apple 明確支援透過 String(localized:defaultValue:...) 分別指定查找索引鍵與來源訊息：第一個引數提供索引鍵，defaultValue 則提供來源字串。例如，語意化索引鍵可以保留 Open collection 作為預設訊息。準備 app 文字以供翻譯

以下完整 app 原始碼示範了這種模式，包含一個靜態標籤與一個整數計數。請使用部署目標為 macOS 12 或以上版本的 macOS SwiftUI app 目標，並以此取代現有的 app 進入點來源檔，而不是再新增一個 @main 宣告。將 Localizable.xcstrings 加入 app 目標。此範例已對照 Apple 的 API 檢查；由於此處沒有 Swift 工具鏈，因此未進行編譯。

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

在此，String(localized:...) 會先解析本地化文字，再顯示產生的字串。Text(verbatim:) 則明確表示這個顯示步驟。Apple 區分立即進行字串本地化與代表可延後查找的 LocalizedStringResource。若要建立可在檢視之間傳遞尚未解析訊息的可重用介面，Apple 建議使用 LocalizedStringResource 這類可本地化型別。LocalizedStringResource、準備 app 文字以供翻譯

使用此方式移轉既有訊息時，請先建置以建立或更新目的項目，再將現有翻譯轉移過去，然後才刪除舊項目。Apple 說明，可選取語言版本並編輯對應的語言欄，直接輸入翻譯。若訊息有變體，請保留所有相關分支，而不是只複製最上層的文字。這種分階段轉移是根據有文件說明的編輯工具整理出的實務移轉程序，並非自動重新命名的保證。使用字串目錄本地化文字並設定變體

擷取與執行階段格式化有何不同？

擷取發生於開發期間：Xcode 會尋找支援的可本地化運算式，並更新目錄。執行階段格式化則發生於 app 解析訊息並插入值時。範例中的計數 7 是執行階段引數；它不應成為固定索引鍵的一部分。

請將整數插值保留在可本地化運算式內。Apple 的 String.LocalizationValue 支援插值，並指引希望使用任意識別碼的開發者改用接受靜態索引鍵並另行指定 defaultValue 的初始化器。先建立一般的呈現字串，並不等同於保留該可本地化訊息及其引數。String.LocalizationValue

若要處理有文法變化的計數訊息，請選取擷取出的計數項目，按住 Control 鍵並按一下，然後選擇 Vary by Plural。補齊來源變體與各現有語言版本所需的變體。對於英文來源，Apple 以 One 的 %lld item 與 Other 的 %lld items 為例。加入插值本身並不代表這些變體已完成。使用字串目錄本地化文字並設定變體

重新命名時，請保留引數型別、位置與意義。若舊訊息包含整數計數，將它替換為預先格式化的字串也會改變格式化契約。對於產生的符號，Xcode 會為含格式指定符的訊息建立帶有型別參數的函式；轉換時請檢查這些函式簽章。在程式碼中使用產生的本地化符號

移除舊項目前先確認內容已保留

使用下列檢查項目確認作業完成。這些檢查能區分目錄問題與查找或格式化問題。

檢查項目	預期結果	失敗時的檢查方向
來源文字	與檢查點相符	預設值遺失或遭到修改
現有翻譯	每個先前的值都能在新索引鍵下使用	轉移不完整或目的地錯誤
變體結構	所有先前的複數與裝置分支都保留	只複製了最上層值
執行階段標籤	顯示預期訊息	索引鍵、字串表、套件或語言版本不符
虛構計數 0、1、7	值正確插入，所需複數分支正常運作	引數或變體不符
舊參照	不再有必須保留的用法	移轉不完整

若要在現有語言版本中測試 Mac app，請選擇 Product > Scheme > Edit Scheme，選取 Run，開啟 Options，然後選擇 App Language。關閉對話框並執行 Mac 目標。對受重新命名影響的語言版本逐一重複檢查，確認實際的標籤與計數訊息。Apple 有說明這套以 Scheme 為基礎的測試流程。執行 app 時測試本地化

如果新索引鍵出現但翻譯是空白，請回到舊項目並轉移遺漏的內容。如果識別碼出現在畫面上，請檢查查找輸入值。如果只有計數失敗，請檢查插值與變體。確認舊項目的內容已妥善處理，且必要參照都已更新後，再移除舊項目。完成後，識別碼會有所變更，同時讀者原本看到的訊息、引數與翻譯都能保留下來。

來源

• 使用字串目錄本地化文字並設定變體 — Apple
• 準備 app 文字以供翻譯 — Apple
• 讓檢視準備好進行本地化 — Apple
• 探索字串目錄 — Apple
• 跟著操作：使用 Xcode 探索本地化 — Apple
• 在程式碼中使用產生的本地化符號 — Apple
• LocalizedStringResource — Apple
• String.LocalizationValue — Apple
• 執行 app 時測試本地化 — Apple