Przydatny komentarz dla tłumacza wyjaśnia, co oznacza etykieta, gdzie się pojawia i co się dzieje, gdy ktoś z niej korzysta. W tym przewodniku pokazano, jak pisać takie komentarze i dołączać je w Xcode w prostej przeglądarce kształtów na Maca, używając syntetycznych angielskich etykiet.

Co powinien wyjaśniać komentarz dla tłumacza?

Zacznij od decyzji, którą musi podjąć tłumacz. Krótka etykieta, taka jak Round, nie określa jasno swojej funkcji gramatycznej ani zamierzonego znaczenia. Komentarz może wskazać, że jest to przymiotnik opisujący kategorię kształtów, i wyjaśnić, że pojawia się nad grupą podglądów. Apple zaleca komentarze, które wyjaśniają, gdzie i jak dany ciąg jest używany w interfejsie. Poznaj katalogi ciągów

Dla osoby przygotowującej etykiety aplikacji na Maca do tłumaczenia konkretne zadanie polega na przekształceniu każdego niejednoznacznego ciągu w krótkie, samodzielne objaśnienie. Tłumacz powinien móc zrozumieć jego przeznaczenie bez przeglądania kodu źródłowego.

Skorzystaj z tego czteroczęściowego narzędzia pomocniczego do pisania. To metoda redakcyjna oparta na wskazówkach Apple, a nie wymagany przez Apple format komentarza:

Część Pytanie, na które należy odpowiedzieć Przykładowy szczegół
Znaczenie Do czego odnosi się tekst źródłowy? Round opisuje kształty o zaokrąglonych konturach.
Rola w interfejsie Jakiego rodzaju tekstem interfejsu jest ta etykieta? Nagłówek kategorii nad podglądami kształtów.
Zachowanie lub lokalizacja Co się dzieje albo co znajduje się w pobliżu? Expand wyświetla szczegóły pod podglądem.
Zmienna treść Co może zawierać każda wstawiana wartość? Pierwsza wartość to nazwa kształtu, a druga to nazwa kolekcji.

Uwzględniaj tylko te elementy, które wpływają na interpretację. Statyczny nagłówek nie wymaga objaśnienia działania. W przypadku przycisku przydaje się jasny opis tego, co robi kliknięcie. W komunikacie z dwiema wstawianymi nazwami należy wyjaśnić relację między nimi.

Apple wyraźnie zaleca objaśnianie elementu interfejsu, otaczającego go interfejsu oraz treści reprezentowanej przez symbole zastępcze. Traktuj te informacje jako praktyczny kontekst dla tłumaczenia. Ćwiczenie z przewodnikiem: poznaj lokalizację w Xcode

Zamieniaj niejasne komentarze w użyteczne opisy ciągów

Poniższe przykłady dotyczą przykładowej przeglądarki kształtów na Maca. Każdy ulepszony komentarz opisuje założone, jasno określone zachowanie interfejsu; przed użyciem dostosuj ten opis do rzeczywistego działania kontrolki.

Etykieta źródłowa Słaby komentarz Bardziej użyteczny komentarz
Shapes Etykieta kształtów. Element nawigacyjny paska bocznego, który otwiera listę kształtów geometrycznych. Rzeczownik w liczbie mnogiej.
Round Tekst kształtu. Nagłówek kategorii nad podglądami kształtów o zaokrąglonych konturach. Przymiotnik opisujący kształty.
Expand Tytuł przycisku. Przycisk pod podglądem kształtu, który wyświetla szczegóły pod podglądem. Czasownik wyrażający działanie.
Selected Etykieta zaznaczenia. Stan wyświetlany obok kształtu obecnie wybranego do podglądu. Opisuje bieżący stan kształtu.

Słabe wersje powtarzają to, co tłumacz już widzi. Mocniejsze uzupełniają brakujące zależności: wskazują, jaki obiekt opisuje przymiotnik, jaką treść wyświetla przycisk lub który element ma dany stan.

W języku angielskim rzeczownik nazywa coś, przymiotnik coś opisuje, a czasownik w trybie rozkazującym wskazuje działanie. Te rozróżnienia pomagają objaśniać zwięzłe sformułowania w interfejsie. Na przykład w tej ilustracji Selected opisuje istniejący stan, natomiast Select na przycisku oznaczałoby żądanie wykonania działania. Określ, którą interpretację wymaga interfejs.

Pisz konkretne komentarze. W przypadku Expand wyjaśnij, czy kontrolka wyświetla tekst ze szczegółami, powiększa podgląd, czy otwiera grupę na pasku bocznym. Nazwanie działania jest bardziej użyteczne niż stwierdzenie, że coś powiększa.

Unikaj narzucania niepotrzebnych zasad formatowania po angielsku. Jeśli interfejs wymaga zwięzłego nagłówka kategorii, napisz o tym. Nie wymyślaj limitu znaków ani nie wymagaj zachowania angielskiego szyku wyrazów w tłumaczeniu. Opisuj rzeczywiste ograniczenie układu tylko wtedy, gdy wiesz, że ma zastosowanie.

Dodawanie komentarzy dla tłumaczy w SwiftUI

Apple opisuje parametr comment: w Text jako sposób dodawania wskazówek dla tłumacza. Gdy wygodny inicjator ciągu danej kontrolki nie pozwala dodać potrzebnego komentarza, użyj jej konstruktora zawartości z jawnym widokiem Text. Apple pokazuje ten wzorzec dla Label i wyjaśnia, że obsługuje go wiele kontrolek SwiftUI. Przygotowywanie widoków do lokalizacji

Poniższy kompletny przykład to niewielka aplikacja SwiftUI na macOS. W Xcode utwórz projekt aplikacji macOS używający SwiftUI, ustaw minimalną wersję systemu na macOS 13 lub nowszą i zastąp wygenerowany kod aplikacji oraz widoku zawartości tym jednym plikiem. Pozostaw tylko jeden punkt wejścia aplikacji. Przykład używa ustalonych, syntetycznych nazw i wyświetla zdanie ze szczegółami po kliknięciu przez użytkownika Expand.

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

Przykład został sprawdzony pod kątem zgodności z udokumentowanymi wzorcami API; nie został tu skompilowany ani uruchomiony, ponieważ dostępne środowisko nie ma łańcucha narzędzi Swift.

W przypadku ciągów przeznaczonych dla użytkownika, tworzonych poza widokiem SwiftUI, Apple opisuje String(localized:comment:). Użyj argumentu komentarza lokalizacyjnego interfejsu API, aby dołączyć kontekst do komunikatu. Apple obsługuje też osobny klucz wyszukiwania i domyślną wartość źródłową, jeśli mają się różnić. Przygotowywanie tekstu aplikacji do tłumaczenia

Objaśnianie wstawianych wartości na podstawie ich znaczenia i relacji

Podpis w przykładzie zawiera dwie interpolacje Swift: \(shapeName) i \(collectionName). Interpolacja Swift wstawia wartości wyrażeń do literału ciągu. Nazwy zmiennych należą do kodu źródłowego; objaśnienie powinno być zrozumiałe także dla osoby, która nie widzi tych nazw. Ciągi i znaki

W przypadku pokazanych syntetycznych wartości angielski podpis brzmi Circle A in Shape Set A. Komentarz wyjaśnia zarówno kolejność wstawianych wartości, jak i ich wzajemną relację: jedna nazywa kształt, a druga kolekcję, która go zawiera. To bardziej użyteczna informacja niż samo stwierdzenie, że argumentami są dwa ciągi.

Podczas sprawdzania komunikatu z interpolowanymi wartościami zadaj trzy pytania:

  1. Jakiego rodzaju treść może pojawić się w każdej pozycji: nazwa, liczba czy inny rodzaj wartości?
  2. Jaka jest relacja między wartościami?
  3. Czy komentarz pozostaje prawdziwy dla każdej wartości, którą aplikacja może przekazać?

Wyraźnie oznaczaj przykłady jako przykładowe. Tutaj Circle A i Shape Set A ilustrują role argumentów. Nie określają wymaganego tłumaczenia ani pełnej listy możliwych nazw.

Liczby wymagają odrębnej decyzji implementacyjnej. Jeśli później dodasz podpis taki jak 3 shapes, komentarz może wyjaśniać, co jest liczone, ale warianty gramatyczne należą do katalogu. Apple opisuje użycie opcji Vary by Plural dla interpolowanych wartości liczbowych, w tym osobnych angielskich form, takich jak 1 item i 2 items. Lokalizowanie i dostosowywanie tekstu za pomocą katalogu ciągów

Znajdowanie i sprawdzanie komentarzy w Xcode

Aby połączyć komentarze w kodzie źródłowym z katalogiem, wykonaj opisane przez Apple czynności:

  1. Wybierz File > New > File from Template.
  2. Filtruj według string, wybierz String Catalog w sekcji Resource i utwórz go z domyślną nazwą Localizable.
  3. Wybierz Product > Build, aby wyodrębnić ciągi do lokalizacji.
  4. W nawigatorze projektu wybierz Localizable.xcstrings.
  5. Wybierz Editor > Assistant, a następnie klucz, aby wyświetlić jego źródło obok katalogu. Lokalizowanie i dostosowywanie tekstu za pomocą katalogu ciągów

Sprawdź, czy komentarz w katalogu odpowiada rzeczywistemu zastosowaniu. W przykładzie Round powinno być opisane jako nagłówek kategorii, a Expand powinno opisywać wyświetlanie szczegółów. Jeśli brakuje ciągu, sprawdź, czy kod używa interfejsu API obsługującego lokalizację i czy włączono opcję Use Compiler to Extract Swift Strings. Apple wskazuje to ustawienie kompilacji jako niezbędne do wyodrębniania ciągów Swift przez kompilator. Poznaj katalogi ciągów

Apple umożliwia też edycję kontekstu bezpośrednio w kolumnie komentarzy katalogu ciągów. Automatyczne generowanie komentarzy wprowadzono w Xcode 26; aktualna dokumentacja opisuje kliknięcie klucza prawym przyciskiem myszy i wybranie opcji Generate Comment. Jeśli ta opcja nie jest dostępna w Twojej konfiguracji, dołącz komentarz w kodzie albo wpisz go w katalogu. Ćwiczenie z przewodnikiem: poznaj lokalizację w Xcode, Lokalizowanie i dostosowywanie tekstu za pomocą katalogu ciągów

Sprawdź wygenerowany tekst pod kątem zgodności z działaniem interfejsu. Opis, który prawidłowo wskazuje przycisk, może nadal wymagać doprecyzowania obiektu lub rezultatu. W tym przykładzie istotne jest, że Expand wyświetla zdanie ze szczegółami poniżej podglądu.

Ustalanie, czy identyczne etykiety mogą współdzielić kontekst

Zgodna pisownia angielska nie oznacza tego samego znaczenia. Załóżmy, że na innym ekranie Round oznacza działanie zaokrąglające wartość liczbową. Połączenie tego zastosowania z nagłówkiem kategorii kształtów wymagałoby od jednego wpisu katalogu opisywania dwóch różnych funkcji gramatycznych.

Apple wyjaśnia, że lokalizowalny ciąg ma klucz wyszukiwania i należy do tabeli; klucze w obrębie tabeli są unikatowe. Dokumentacja Swift Apple opisuje również obsługiwany sposób użycia odrębnego klucza z domyślną wartością źródłową. Używaj osobnych kluczy, gdy znaczenia wymagają niezależnych tłumaczeń, nawet jeśli ich angielskie wartości wyświetlane są identyczne. Poznaj katalogi ciągów, Przygotowywanie tekstu aplikacji do tłumaczenia

Praktyczna zasada decyzyjna: sprawdź, czy jeden komentarz może trafnie objaśnić każde użycie. Jeśli znaczenie i rola w interfejsie pozostają spójne, wspólny kontekst może być odpowiedni. Jeśli objaśnienie musi opisywać niezwiązane ze sobą działania, rozważ zmianę struktury kluczy. To wniosek projektowy wynikający z modelu kluczy i tabel Apple, a nie zasada wymagająca osobnego ciągu dla każdej kontrolki.

Przed przekazaniem etykiety do tłumaczenia przeczytaj jej komentarz bez kodu źródłowego. Powinien pozwalać tłumaczowi rozpoznać zamierzone znaczenie, określić przybliżone miejsce tekstu w interfejsie i zrozumieć wstawianą treść. Zmieniaj komentarz za każdym razem, gdy zmienia się zachowanie lub rola etykiety, aby objaśnienie nadal opisywało interfejs widoczny dla użytkownika.

Źródła