Aby zmienić klucz katalogu ciągów w Xcode, zachowaj osobno komunikat źródłowy, zaktualizuj odwołania w kodzie i sprawdź każde istniejące tłumaczenie oraz wariant. W przypadku ciągów wyodrębnionych z kodu Xcode 26 oferuje refaktoryzację konwersji; sama zmiana klucza wyszukiwania nie wystarczy.

Ten przewodnik jest przeznaczony dla osób utrzymujących aplikację SwiftUI na Maca z istniejącym katalogiem .xcstrings. Zadanie polega na zastąpieniu kluczy w formie komunikatów znaczącymi identyfikatorami przy zachowaniu wyświetlanego tekstu i tłumaczeń. Apple dokumentuje opisane niżej interfejsy API i proces konwersji, ale nie gwarantuje, że dowolna zmiana klucza automatycznie przeniesie wszystkie tłumaczenia.

Co musi pozostać bez zmian po zmianie klucza?

Komunikat lokalizowalny to coś więcej niż identyfikator. Apple opisuje jego klucz, wartość domyślną, komentarz i tabelę ciągów jako osobne elementy. Klucz identyfikuje komunikat w czasie działania; wartość domyślna określa tekst źródłowy. Katalog przechowuje tłumaczenia i metadane tabeli. Traktuj zmianę nazwy jako skoordynowaną zmianę kontraktu tego komunikatu. Odkrywanie katalogów ciągów

Przed edycją zanotuj poniższe informacje dla każdego wpisu, którego dotyczy zmiana. Te przykłady syntetyczne ilustrują zmianę nazwy; nie są wynikami pomiarów.

Element Przed zmianą Zamierzony wynik
Klucz wyszukiwania Open collection collection.open
Komunikat źródłowy Open collection Bez zmian
Tabela Localizable Bez zmian
Pakiet Pakiet głównej aplikacji Bez zmian
Kontekst dla tłumacza Przycisk otwierający wybraną kolekcję Zachowany
Istniejące tłumaczenia Obecne wartości we wszystkich lokalizacjach Zachowane
Argumenty liczbowe, jeśli występują Liczba całkowita Ten sam typ i znaczenie
Warianty liczby mnogiej lub urządzenia Istniejące gałęzie Zachowane

Użyj tych informacji do porównania. Samo pomyślne zbudowanie aplikacji nie potwierdza, że tłumaczenia przetrwały: aplikacja może nadal wyświetlać komunikat domyślny, gdy nie znajdzie pasującego wpisu. Dokumentacja SwiftUI podaje, że zlokalizowany klucz może zostać wyświetlony bezpośrednio, jeśli nie ma go w katalogu. W przypadku znaczącego klucza interfejs może wtedy pokazać identyfikator, na przykład collection.open. Przygotowywanie widoków do lokalizacji

Znajdź źródło przed edycją katalogu

Otwórz istniejący katalog w Nawigatorze projektu Xcode. Wybierz Editor > Assistant, a następnie wskaż wpis, aby sprawdzić jego źródło. Apple opisuje też strzałkę obok klucza i przykładowe użycia w Inspektorze atrybutów jako sposoby lokalizowania odwołań. W przypadku ciągów wyodrębnionych z kodu po zmianach w źródłach wybierz Product > Build, aby zsynchronizować katalog. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

Sprawdź, czy wpis został wyodrębniony z kodu, czy jest zarządzany ręcznie. Apple wyjaśnia, że w przypadku wyodrębnionych komunikatów źródłem prawdy jest kod: kompilacje synchronizują ich wartości źródłowe. Przetłumaczony wpis, który przestaje być wyodrębniany, pozostaje jako Stale; nieprzetłumaczony wpis może zostać usunięty. Wyodrębnianie nie aktualizuje ani nie usuwa wpisów zarządzanych ręcznie. Dlatego nie usuwaj starego przetłumaczonego wpisu tylko dlatego, że pojawił się nowy. Odkrywanie katalogów ciągów

Przed dalszymi działaniami utwórz punkt kontrolny, do którego można wrócić, a po zmianach porównaj z nim wpis. Podczas tego zadania pozostaw bez zmian tabelę i pakiet, aby ograniczyć możliwe przyczyny brakujących tłumaczeń. Interfejsy API lokalizacji Apple przyjmują informacje o tabeli i pakiecie właśnie dlatego, że określają one, gdzie wyszukiwany jest komunikat. Przygotowywanie tekstu aplikacji do tłumaczenia

Użyj refaktoryzacji konwersji Xcode w przypadku ciągów wyodrębnionych z kodu

Jeśli projekt korzysta z Xcode 26 lub nowszego, rozważ konwersję istniejącego wyodrębnionego wpisu na wygenerowany symbol lokalizowalny. Apple wprowadziło ten proces w Xcode 26 i pokazuje zmianę klucza na znaczącą nazwę podczas konwersji. To udokumentowana metoda, która pozwala zmienić sposób identyfikowania komunikatu i odwoływania się do niego. Samouczek: odkrywanie lokalizacji w Xcode

  1. W ustawieniach kompilacji sprawdź, czy opcja Generate String Catalog Symbols ma wartość Yes, jeśli trzeba ją włączyć w istniejącym projekcie.
  2. W edytorze katalogu zaznacz istniejący klucz, kliknij go z wciśniętym klawiszem Control i wybierz Refactor > Convert Strings to Symbols.
  3. Sprawdź podgląd pokazujący zmianę klucza katalogu i lokalizacje w kodzie, których dotyczy zmiana.
  4. W interfejsie konwersji edytuj proponowaną nazwę semantyczną oraz, jeśli dotyczy, nazwy argumentów.
  5. Porównaj bieżący i zmodyfikowany kod w podświetlonym podglądzie, a następnie kliknij Convert.
  6. Zbuduj aplikację i porównaj wynikowy wpis z punktem kontrolnym, uwzględniając tłumaczenia i warianty.

Apple dokumentuje te ustawienia konwersji i pokazuje przykłady wygenerowanego użycia w Inspektorze atrybutów. Skorzystaj z tych przykładów zamiast zgadywać identyfikator Swift na podstawie znaków interpunkcyjnych w proponowanym kluczu katalogu. Wygenerowane symbole zależą od informacji w katalogu, a tabele inne niż domyślna wprowadzają przestrzeń nazw tabeli. Korzystanie w kodzie z wygenerowanych symboli lokalizowalnych

Ta refaktoryzacja służy konkretnie do przejścia od ciągów wyodrębnionych z kodu do wygenerowanych symboli. Cytowana dokumentacja nie potwierdza istnienia uniwersalnej operacji zmiany nazwy dla każdego wpisu zarządzanego ręcznie ani każdego zewnętrznego odwołania. Jeśli podgląd pomija wymagane odwołanie, uwzględnij je jawnie, zanim usuniesz poprzedni klucz.

Zachowaj wyodrębnianie, jeśli wolisz przechowywać klucze i wartości domyślne w kodzie

Możesz też pozostać przy wyodrębnianiu sterowanym kodem. Apple wyraźnie obsługuje oddzielne klucze wyszukiwania i komunikaty źródłowe za pomocą String(localized:defaultValue:...): pierwszy argument określa klucz, a defaultValue — ciąg źródłowy. Na przykład znaczący klucz może zachować Open collection jako komunikat domyślny. Przygotowywanie tekstu aplikacji do tłumaczenia

Poniższy kompletny kod aplikacji pokazuje ten wzorzec dla jednej etykiety statycznej i jednej liczby całkowitej. Użyj celu aplikacji SwiftUI na macOS z minimalną wersją systemu macOS 12 lub nowszą i zastąp istniejący kod wejściowy aplikacji, zamiast dodawać drugą deklarację @main. Dodaj Localizable.xcstrings do celu aplikacji. Przykład sprawdzono pod kątem zgodności z interfejsami API Apple; nie został tutaj skompilowany, ponieważ nie była dostępna toolchain 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()
    }
}

Tutaj String(localized:...) zwraca zlokalizowany tekst, zanim wynikowy ciąg zostanie wyświetlony. Text(verbatim:) jawnie wykonuje ten etap wyświetlania. Apple odróżnia natychmiastową lokalizację ciągu od LocalizedStringResource, która reprezentuje wyszukiwanie możliwe do odroczenia. W przypadku wielokrotnego użytku interfejsów, które przekazują nierozwiązane komunikaty między widokami, Apple zaleca lokalizowalny typ, taki jak LocalizedStringResource. LocalizedStringResource, Przygotowywanie tekstu aplikacji do tłumaczenia

Migrując istniejący komunikat tą metodą, zbuduj aplikację, aby utworzyć lub zaktualizować wpis docelowy, a następnie przenieś istniejące tłumaczenia przed usunięciem poprzedniego wpisu. Apple opisuje bezpośrednie wprowadzanie tłumaczeń po wybraniu lokalizacji i edycji odpowiedniej kolumny języka. W przypadku zróżnicowanego komunikatu zachowaj każdą odpowiednią gałąź, zamiast kopiować tylko tekst na najwyższym poziomie. To etapowa procedura migracji wynikająca z udokumentowanych narzędzi edycji, a nie gwarancja automatycznej zmiany nazwy. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

Czym różnią się wyodrębnianie i formatowanie w czasie działania?

Wyodrębnianie odbywa się podczas programowania: Xcode wykrywa obsługiwane wyrażenia lokalizowalne i aktualizuje katalog. Formatowanie w czasie działania następuje, gdy aplikacja odczytuje komunikat i wstawia wartości. Przykładowe zliczenie 7 jest argumentem czasu działania; nie powinno stać się częścią stabilnego klucza.

Pozostaw interpolację liczby całkowitej wewnątrz wyrażenia lokalizowalnego. Typ String.LocalizationValue firmy Apple obsługuje interpolację i kieruje deweloperów, którzy chcą używać dowolnych identyfikatorów, do inicjalizatorów ze statycznym kluczem i osobnym defaultValue. Najpierw utworzony zwykły, sformatowany ciąg nie zachowuje lokalizowalnego komunikatu ani jego argumentów. String.LocalizationValue

W przypadku komunikatów o liczbie mnogiej zaznacz wyodrębniony wpis z liczebnością, kliknij go z wciśniętym klawiszem Control i wybierz Vary by Plural. Uzupełnij warianty źródłowe i wymagane warianty dla każdej istniejącej lokalizacji. Dla tekstu źródłowego w języku angielskim Apple pokazuje One z wartością %lld item oraz Other z wartością %lld items. Samo dodanie interpolacji nie wystarcza, by te warianty były gotowe. Lokalizowanie i różnicowanie tekstu za pomocą katalogu ciągów

Podczas zmiany nazwy zachowaj typy, pozycje i znaczenie argumentów. Jeśli stary komunikat zawierał liczbę całkowitą, zastąpienie jej wstępnie sformatowanym ciągiem zmienia też kontrakt formatowania. W przypadku wygenerowanych symboli Xcode tworzy funkcje z parametrami o typach dla komunikatów zawierających specyfikatory formatu; sprawdź te sygnatury podczas konwersji. Korzystanie w kodzie z wygenerowanych symboli lokalizowalnych

Sprawdź, czy tłumaczenia zostały zachowane, zanim usuniesz stary wpis

Użyj poniższych kontroli, aby sprawdzić, czy zadanie zostało wykonane. Pozwalają one odróżnić problem z katalogiem od problemu z wyszukiwaniem lub formatowaniem.

Kontrola Oczekiwany wynik Co sprawdzić w razie niepowodzenia
Tekst źródłowy Zgodny z punktem kontrolnym Brakująca lub zmieniona wartość domyślna
Istniejące tłumaczenia Wszystkie poprzednie wartości są dostępne pod nowym kluczem Niepełne przeniesienie lub niewłaściwe miejsce docelowe
Struktura wariantów Zachowane wszystkie poprzednie gałęzie liczby mnogiej i urządzeń Skopiowano tylko wartość na najwyższym poziomie
Etykieta w czasie działania Wyświetla zamierzony komunikat Niezgodność klucza, tabeli, pakietu lub lokalizacji
Syntetyczne liczebności 0, 1, 7 Wartości są prawidłowo wstawiane i wymagane gałęzie liczby mnogiej działają Niezgodność argumentu lub wariantu
Stare odwołania Nie pozostało żadne wymagane użycie Niekompletna migracja

Aby przetestować aplikację Mac w istniejącej lokalizacji, wybierz Product > Scheme > Edit Scheme, zaznacz Run, otwórz Options i wybierz App Language. Zamknij okno dialogowe i uruchom cel Mac. Powtórz test dla lokalizacji objętych zmianą nazwy, sprawdzając rzeczywistą etykietę i komunikat z liczebnością. Apple dokumentuje ten sposób testowania za pomocą schematu. Testowanie lokalizacji podczas uruchamiania aplikacji

Jeśli pojawi się nowy klucz, ale jego tłumaczenie będzie puste, wróć do poprzedniego wpisu i przenieś brakującą treść. Jeśli na ekranie pojawi się identyfikator, sprawdź dane używane do wyszukiwania. Jeśli nie działają tylko liczebności, sprawdź interpolację i warianty. Usuń stary wpis po uwzględnieniu jego zawartości i przeniesieniu wymaganych odwołań. Gotowa zmiana powinna zmienić identyfikator przy zachowaniu komunikatu, jego argumentów i tłumaczeń, które otrzymują już czytelnicy.

Źródła