프레임워크의 현지화 키를 확인하려면 리소스 번들과 문자열 테이블을 모두 전달하세요. 이 가이드에서는 프레임워크가 소유한 레이블이 Mac 앱에 올바르게 표시되도록 한 다음, 결과가 대체 텍스트가 아니라 테이블에서 나온 것인지 확인하는 방법을 보여줍니다.

이 작업은 의도적으로 간단하게 구성했습니다. 프레임워크의 Panel.xcstrings 카탈로그에서 합성 레이블 Open panel을 표시합니다. Xcode의 Mac 앱 프로젝트와 직접 관리하는 프레임워크 타깃이 필요합니다. 기본 예제는 Xcode 26 이상을 사용하고 macOS 12 이상을 대상으로 합니다. Apple 문서에 따르면 현지화 문자열 초기화자는 macOS 12부터 사용할 수 있습니다. Swift 초기화자 문서.

코드를 변경하기 전에 번들, 테이블, 키를 확인하세요

현지화된 메시지는 세 가지 좌표를 명시하는 조회로 다루세요. 번들은 리소스 소유자를 식별하고, 테이블은 해당 번들 내 문자열 그룹을 식별하며, 키는 그 테이블 안의 항목을 식별합니다. 프레임워크와 앱 타깃 모두 문자열 리소스를 포함할 수 있으므로 Apple의 현지화 API는 번들과 테이블을 별도로 지정합니다. 앱 텍스트를 번역할 수 있도록 준비하기.

이 예제에서는 카탈로그를 열기 전에 다음 계약을 적어 두세요. 이는 예시 이름이며 Apple에서 요구하는 이름은 아닙니다.

항목 예시 값 용도
리소스 소유자 사용자의 프레임워크 타깃 카탈로그를 포함합니다
카탈로그 파일 Panel.xcstrings 테이블의 원문과 번역을 저장합니다
테이블 인수 Panel 확장자를 제외한 이름으로 해당 카탈로그를 선택합니다
키 PANEL_OPEN_ACTION 메시지를 식별합니다
영어 원문 값 Open panel 읽기 쉬운 인터페이스 텍스트를 제공합니다
주석 Label for the action that opens the panel. 메시지의 용도를 설명합니다

table: "Panel"을 전달하면 Panel.xcstrings에 해당하는 테이블이 선택됩니다. 테이블을 지정하지 않으면 Localizable이 선택됩니다. 마찬가지로 번들을 지정하지 않으면 문자열 초기화자는 기본 앱 번들을 검색합니다. 따라서 프레임워크 카탈로그의 키를 찾으려면 프레임워크의 번들과 올바른 테이블을 모두 지정해야 합니다. Swift 현지화 문자열 매개변수.

이 내용을 바탕으로 유용한 진단 순서를 세울 수 있습니다. 먼저 소유자를 확인하고, 다음으로 테이블, 마지막으로 항목을 확인하세요. 메시지가 프레임워크에 속하는데 앱의 리소스를 가리키고 있다면 키의 다른 표기를 검색해도 문제가 해결되지 않습니다.

프레임워크 타깃에 문자열 카탈로그 추가하기

Xcode에서 File > New > File from Template을 선택하고, 플랫폼을 선택한 다음 string을 검색하고 String Catalog를 선택하세요. 파일 이름을 Panel로 지정합니다. 카탈로그가 이를 참조할 프레임워크 소스와 함께 프레임워크 타깃에 속하는지 확인하세요. Apple의 카탈로그 작업 흐름에서는 사용자 지정 카탈로그 이름을 사용할 수 있으며, 프레임워크 예제에서는 프레임워크 타깃 안에 카탈로그를 만듭니다. 문자열 카탈로그로 텍스트 현지화 및 변형하기, Apple의 프레임워크 현지화 예제.

이 예제에서는 표시되는 문구를 키로 사용하지 않고 의미 기반 키를 사용합니다. PANEL_OPEN_ACTION를 식별자로, Open panel을 기본값으로 지정하면 코드에서 두 요소를 모두 명시할 수 있습니다. Apple은 정적 키와 별도의 기본 현지화 값을 받는 초기화자를 통해 이 방식을 지원합니다. Swift 정적 키 초기화자.

아래 소스를 추가한 뒤 프레임워크 타깃을 빌드하세요. Xcode는 빌드 중에 현지화 가능한 API 호출을 찾아 관련 카탈로그를 업데이트합니다. Panel.xcstrings를 열고 PANEL_OPEN_ACTION, 영어 원문 값 Open panel, 설명 주석이 들어 있는지 확인하세요. 항목이 없다면 소스의 타깃 멤버십과 해당 소스를 포함한 타깃을 빌드했는지 확인하세요. Apple은 카탈로그 항목에 연결된 코드를 살펴볼 수 있도록 Editor > Assistant도 제공합니다. 문자열 카탈로그 채우기 및 검사하기.

프레임워크 내부에서 메시지 확인하기

이 전체 소스 파일을 프레임워크 타깃에 넣으세요. 이 파일은 현지화된 문자열과 이를 포함하는 Mac 앱에서 표시할 수 있는 간단한 SwiftUI 레이블을 정의합니다. 다음 절에서 사용할 진단 메서드도 포함합니다. 코드는 Apple이 문서화한 시그니처를 기준으로 확인했지만, Swift 컴파일러를 사용할 수 없어 여기서 실행하지는 않았습니다.

import Foundation
import SwiftUI

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: #bundle,
            comment: "Label for the action that opens the panel."
        )
    }

    public static func lookupReport() -> String {
        let missingMarker = "__PANEL_LOOKUP_MISSING__"
        let result = #bundle.localizedString(
            forKey: "PANEL_OPEN_ACTION",
            value: missingMarker,
            table: "Panel"
        )

        if result == missingMarker {
            return "No entry resolved from the selected bundle and table."
        }

        return "Resolved table value: \(result)"
    }
}

public struct PanelActionLabel: View {
    public init() {}

    public var body: some View {
        Text(verbatim: PanelMessages.openPanel)
    }
}

#bundle 표현식은 작성한 위치에서 평가됩니다. 이 프레임워크 소스 안에서는 프레임워크 타깃에 연결된 번들을 제공합니다. 같은 표현식을 앱 타깃 소스로 옮기면 앱의 번들을 제공합니다. Swift 패키지 타깃의 경우 이 매크로가 해당 타깃의 리소스 번들을 제공한다고 Apple은 설명합니다. 조회 코드를 해당 리소스를 소유한 코드 옆에 두세요. Foundation의 번들 매크로.

선언은 현지화 확인이 이미 끝난 일반 String을 반환합니다. 뷰는 Text(verbatim:)을 사용해 결과를 명시적으로 표시합니다. 공개 뷰는 레이블일 뿐이므로, 텍스트를 표시해야 하는 기존 앱 뷰에 추가하세요.

번들 매크로를 사용할 수 없을 때 프레임워크 클래스를 사용하세요

Apple은 프레임워크에 정의된 클래스를 통해서도 프레임워크 번들을 찾을 수 있도록 지원합니다. 자체 리소스를 포함하는 일반적인 프레임워크라면 다음을 완전한 대체 메시지 제공자로 사용할 수 있습니다. 앞서 선언한 PanelMessages 대신 이것을 사용하고, 위에서 설명한 카탈로그 및 배포 대상 요구 사항을 따르세요.

import Foundation

private final class PanelBundleAnchor: NSObject {}

public enum PanelMessages {
    public static var openPanel: String {
        String(
            localized: "PANEL_OPEN_ACTION",
            defaultValue: "Open panel",
            table: "Panel",
            bundle: Bundle(for: PanelBundleAnchor.self),
            comment: "Label for the action that opens the panel."
        )
    }
}

기준 클래스는 사용하려는 리소스가 속한 프레임워크에 컴파일되어 있어야 합니다. Apple 문서에 따르면 Bundle(for:)는 지정된 클래스와 연결된 번들을 반환하며, 해당되는 경우 프레임워크 번들도 반환합니다. 앱에 컴파일된 기준 클래스는 앱 번들을 가리킵니다. 패키지 리소스나 별도 번들에 있는 리소스라면 실제 리소스 번들을 선택하세요. 클래스가 어디에 있는지만으로는 해당 리소스의 소유권을 확인할 수 없습니다. Bundle 클래스 기반 초기화자, 매크로를 사용한 리소스 번들 선택.

읽기 쉬운 텍스트가 조회 성공으로 나온 것인지 확인하기

화면에 Open panel이 표시된다고 해서 카탈로그 조회가 성공했다는 증거가 되지는 않습니다. 조회가 실패하면 초기화자는 defaultValue을 반환하므로, 같은 텍스트가 성공적인 조회 결과일 수도 있고 대체 값일 수도 있습니다. 읽기 쉬운 인터페이스 텍스트를 제공할 때는 유용하지만, 개발 중에 잘못된 번들이나 테이블을 사용하고 있어도 알아차리지 못하게 할 수 있습니다. Swift 기본값 동작.

첫 번째 소스 파일의 lookupReport() 메서드는 이 모호함을 해결합니다. 실제 카탈로그 값으로 사용해서는 안 되는 고유한 대체 표식으로 조회를 수행합니다. 실행 중인 앱이나 기존 디버그 환경에서 반환값을 확인하세요. 확인된 항목이 없다고 나오면 번역을 수정하기 전에 선택된 리소스를 조사하세요.

이 진단은 Bundle.localizedString(forKey:value:table:)의 문서화된 동작을 그대로 따릅니다. 키가 없고 제공된 대체 값이 비어 있지 않으면 메서드는 해당 대체 값을 반환합니다. 키가 없고 대체 값이 nil이거나 비어 있으면 대신 키를 반환합니다. 표식을 사용하면 실패를 정상적인 원문 텍스트와 쉽게 구분할 수 있습니다. Bundle 현지화 문자열 반환값).

관찰 결과 다음 확인 사항
진단 결과에서 항목을 찾지 못했다는 메시지가 반환됨 선택한 번들에 카탈로그가 빌드되어 있는지 확인한 다음 Panel과 PANEL_OPEN_ACTION을 확인하세요
진단 결과에서 예상하지 못한 값이 확인됨 선택한 테이블에서 해당 항목과 현재 실행에 사용된 언어를 확인하세요
진단 결과는 올바르지만 인터페이스 표시가 다름 인터페이스가 실제로 어떤 값을 표시하는지 추적하세요
번역된 환경에서 영어 원문 값이 표시됨 항목의 번역과 실행 구성을 확인하세요. 조회에 성공했다고 해서 요청한 번역이 있다는 뜻은 아닙니다

이 표는 조회 계약을 바탕으로 만든 문제 해결 순서입니다. 표식 테스트에 성공하면 조회가 항목을 반환했다는 것은 확인할 수 있지만, 지원되는 모든 언어의 번역이 완료되었다는 뜻은 아닙니다. 리소스 확인과 번역 완전성은 별도로 점검하세요.

Mac 앱에서 선택한 언어로 레이블 테스트하기

추가 언어를 지원하는 앱이라면 카탈로그 사이드바에서 해당 언어를 선택하고 항목의 텍스트 필드에 번역을 입력하세요. 그런 다음 이를 포함하는 Mac 앱에서 테스트합니다. Apple 문서에 따르면 카탈로그 편집기에서 번역을 직접 입력할 수 있으며, 작업하는 동안 각 항목의 번역 상태가 업데이트됩니다. 문자열 카탈로그에 번역 추가하기.

디버그 실행 언어를 지정하려면 Product > Scheme > Edit Scheme을 선택하고 Run을 선택한 뒤 Options를 여세요. App Language를 프로젝트에서 지원하는 언어로 설정하고 편집기를 닫은 다음 Mac 앱을 다시 실행합니다. 실행 시 시스템의 언어 설정을 따르게 하려면 System Language를 선택하세요. 앱 실행 시 현지화 테스트하기.

문자열 초기화자의 locale: 인수를 이 언어 테스트의 대용으로 사용하지 마세요. Apple 문서에 따르면 이 인수는 숫자와 같은 보간 값의 현지화를 제어하며, 현지화 문자열 조회에 사용되는 로캘은 바꾸지 않습니다. 이 예제의 레이블에는 보간 값이 없으므로 해당 인수를 생략합니다. Swift 현지화 문자열의 locale 매개변수.

최종 계약은 간단하고 명확하게 유지하세요. Panel.xcstrings는 프레임워크 소유이고, 조회는 Panel을 선택하며, PANEL_OPEN_ACTION은 레이블을 식별합니다. 진단으로 항목을 확인한 다음 앱에서 선택한 실행 언어로 번역이 표시되는지 확인하세요. 이 순서를 따르면 앱이 읽지 않을 수도 있는 문구를 다듬는 데 시간을 쓰기 전에 리소스 조회 문제를 바로잡을 수 있습니다.

출처