.XCSTRINGS - Apple Strings Catalog (Strings)

컨텐츠는 영어 텍스트를 Phrase Language AI를 이용해 기계 번역한 것입니다.

파일 확장명	.xcstrings
API 확장	strings_catalog
가져오기	예
내보내기	예
복수형 지원	예
설명 지원	예
형식 옵션 파일을 업로드 및/또는 다운로드할 때 지정할 수 있는 옵션입니다. 업로드/다운로드 방식(API, CLI, Repo 동기화 등)에 따라 쿼리 매개변수 `Upload`, `Download` 또는 `phrase.yml` 구성 파일에서 지정할 수 있습니다.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings)는 Xcode 15에서 도입된 현지화 형식입니다. 이 형식은 복수형 처리, 기기별 변형 등을 위한 구조화된 형식을 지원하여 개발자가 현지화된 문자열을 관리하는 방식을 향상시킵니다. 이 형식은 iOS 및 macOS 애플리케이션의 현지화를 관리하기 위한 권장 접근 방식이 되고 있습니다.

comment, extractionState 및 shouldTranslate 메타데이터 필드는 Xcode와의 호환성을 보장하기 위해 필요한 순서대로 가져오고 내보냅니다.

Phrase는 가져오기 시 Xcode 번역 상태를 가장 유사한 Strings 대응 항목으로 매핑하고, 내보내기 시 다시 Xcode 호환 값으로 변환합니다. 특정 매핑이 적용되지 않는 경우, translated가 기본 내보내기 값으로 사용됩니다. 필요한 경우 Ignore translation state on import 옵션을 사용하여 상태 매핑을 건너뜁니다.

코드 샘플

{
  "sourceLanguage": "en",
  "strings": {
    "Sync Warning": {
      "comment": "Sync function unavailable message",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Cloud Sync must be enabled to use this feature."
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "La synchronisation cloud doit être activée pour utiliser cette fonction."
          }
        }
      }
    },
    "Chosen Collections": {
      "comment": "View title indicating selected photo collections",
      "localizations": {
        "fr": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collection sélectionnée"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collections sélectionnées"
                }
              }
            }
          }
        },
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collection Selected"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collections Selected"
                }
              }
            }
          }
        }
      }
    },
    "Settings Hub": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Centro de configuración"
          }
        }
      }
    }
  },
  "version": ## 8.
}

Phrase CLI를 사용할 때, 파일 내보내기는 .phrase.yml 구성 파일에 정의된 구조를 따릅니다. 풀(pull) 작업 중에 여러 언어가 단일 .XCSTRINGS 파일로 내보내지도록 하려면:

CLI 구성 파일에 하나의 파일 대상만 지정하십시오.
locale_ids 매개변수를 사용하여 내보내기에 포함된 모든 언어 로캘을 나열하십시오.

예시 .phrase.yml 구성

pull:
  targets:
    - file: ./i18n-test/Localizable.xcstrings
      params:
        locale_id: en # Main language for the download
        locale_ids: # Additional languages to include
          - de
          - es
          - fr 
        file_format: strings_catalog

기기 변형

Apple Strings Catalog는 기기 변형을 지원하며, 이를 통해 사용 중인 Apple 기기에 따라 동일한 키에 대해 서로 다른 번역 콘텐츠를 사용할 수 있습니다.

Phrase Strings에서 기기 변형을 처리하기 위해, 구분 기호 |==|를 사용하여 각 기기에 대한 별도의 키가 생성됩니다. .XCSTRINGS 파일을 가져올 때, 이 구분 기호를 사용하여 기본 키 이름에 기기 유형이 추가됩니다.

사례

applewatch 장치를 위한 %lld Product(s) Ordered 키는 Phrase Strings로 %lld Product(s) Ordered|==|device.applewatch라는 복수형 키로 가져옵니다.

내보내는 동안 Phrase Strings는 구분 기호를 사용하여 장치 변형을 감지하고 Apple의 현지화 형식을 위해 원래의 중첩 구조를 복원합니다.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "주문된 제품 수를 나타내며, 장치별 변형이 있습니다",
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "applewatch": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Apple Watch)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Apple Watch)"
                      }
                    }
                  }
                }
              },
              "ipad": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPad)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPad)"
                      }
                    }
                  }
                }
              },
              "iphone": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPhone)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPhone)"
                      }
                    }
                  }
                }
              },
              "mac": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Mac)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Mac)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit(s) commandé(s)"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produits commandés"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit commandé"
                }
              }
            }
          }
        }
      }
    }
  }
}

문자열 대체

Apple Strings Catalog는 동적 콘텐츠를 위한 유연한 자리 표시자를 제공하는 문자열 대체를 지원합니다.

Phrase Strings에서 문자열 대체를 처리하려면 구분 기호 |==|를 사용하여 별도의 키를 생성합니다. .XCSTRINGS 파일을 가져올 때, 이 구분 기호를 사용하여 기본 키 이름에 대체가 추가됩니다.

Phrase Strings는 프로젝트에서 직접 대체 문자열을 생성하는 기능도 지원합니다. 대체 구조를 수동으로 생성할 때는 내보내기 중에 올바른 중첩 형식이 생성되도록 기본 키와 해당 대체 키를 정의해야 합니다.

대체에는 항상 keyName|==|substitution.[specifier]와 같은 특정 키 명명 형식이 필요합니다.

예: 기존 .XCSTRINGS 파일에서 대체 구조 가져오기

BIRDS 대체를 위한 birdSightingAlert 키는 Phrase Strings로 birdSightingAlert|==|substitution.BIRDS라는 복수형 키로 가져옵니다.

내보내는 동안 Phrase Strings는 구분 기호를 사용하여 대체를 감지하고 Apple의 현지화 형식을 위해 원래의 중첩 구조를 복원합니다.

"birdSightingAlert": {
  "comment": "Alert message indicating the number of birds spotted",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "new",
        "value": "You spotted %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier": "BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "new",
                  "value": "a bird"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "new",
                  "value": "several birds"
                }
              },
              "zero": {
                "stringUnit": {
                  "state": "new",
                  "value": "no birds"
                }
              }
            }
          }
        }
      }
    }
  }

예: 처음부터 대체 문자열 생성

기본 키

keyName이라는 기본 키는 대체 자리 표시자 %#@format@를 포함하는 최상위 형식 문자열을 나타냅니다.

내보낼 때 이 키는 항목에 대한 기본 stringUnit으로 기록됩니다:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

대체 키

대체 문자열은 대체 명명 형식을 사용하는 별도의 키로 정의됩니다: keyName|==|substitution.li.

이 키에는 일반적으로 복수형 변형이 포함된 대체 텍스트가 들어 있습니다. 내보내는 동안 Phrase Strings는 |==|substitution. 구분 기호를 사용하여 대체를 감지하고 기본 키 아래에 해당하는 중첩 구조를 복원합니다:

{
  "sourceLanguage": "en",
  "strings": {
    "keyName": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "%#@format@"
          },
          "substitutions": {
            "li": {
              "formatSpecifier": "li",
              "variations": {
                "plural": {
                  "one": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ day"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ days"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": ## 8.
}

형식 옵션

식별자	convert_placeholder
유형	부울
업로드	아니요
다운로드	예
기본값	false
설명	플레이스홀더는 형식별 요구 사항에 맞게 변환됩니다. 예: `$s`→`$@`, `%s`→`%@`

식별자	default_extraction_state
유형	문자열
업로드	아니요
다운로드	예
기본값	null
설명	키에 추출 상태가 정의되어 있지 않을 때 내보낸 파일의 키에 기록되는 `extractionState` 값을 정의합니다. 키에 이미 `extractionState`가 포함되어 있는 경우, 내보내는 동안 해당 값이 유지됩니다. 지원되는 환경: UI 다운로드 API CLI(`.phrase.yml` 구성 사용) 및 Repo Sync

식별자	locale_code_mapping
유형	객체
업로드	예
다운로드	예
기본값	}
설명	Phrase 로캘 코드를 .XCSTRINGS 파일에 기록된 로캘 코드로 매핑합니다. 각 키는 Phrase 로캘 코드이며, 각 값은 파일에 기록되는 코드입니다. 예: { "en": "en-GB", "fr": "fr-FR" } 다운로드 시, Phrase는 `sourceLanguage` 필드와 매핑 키와 일치하는 모든 `localizations` 키를 매핑된 값으로 다시 작성합니다. 매핑이 없는 코드는 변경되지 않습니다. 업로드 시, Phrase는 동일한 매핑을 역으로 적용하여 `sourceLanguage`를 포함한 파일 로케일 코드를 해당 Phrase 로케일 코드로 다시 변환합니다. 이 옵션은 .XCSTRINGS 파일 자체에서 읽고 쓰는 로케일 코드에만 영향을 미칩니다. 예를 들어 Git 통합 파일 명명 패턴에 사용되는 파일 이름 기반 로케일 매핑은 .XCSTRINGS 내부의 코드가 아닌 파일 경로를 매핑하는 별도의 설정입니다.

iOS Strings(.strings)에서 Strings Catalog(.xcstrings)로 마이그레이션하기

레거시 iOS Strings 형식(.strings)은 번역 콘텐츠의 리터럴 백슬래시-n 시퀀스(\\n)를 실제 줄 바꿈과 동일하게 취급합니다. 결과적으로, .strings 형식을 사용하는 동안 생성되거나 편집된 번역에는 실제 줄 바꿈 문자 대신 리터럴 텍스트 \\n가 포함될 수 있습니다.

Strings Catalog (.xcstrings)은 JSON 기반 형식입니다. 리터럴 \\n 시퀀스를 포함하는 콘텐츠가 .xcstrings로 내보내지면, JSON 인코딩은 해당 리터럴 텍스트를 파일 내에서 \\\\n로 이스케이프 처리합니다. 이 동작은 이중 이스케이프 오류가 아닙니다. 이는 번역 콘텐츠에 이미 존재하는 리터럴 \\n 텍스트를 반영하며, 올바른 JSON 이스케이프를 사용하여 내보내집니다.

.strings에서 .xcstrings로 마이그레이션한 후 이를 해결하려면, 영향을 받는 콘텐츠의 리터럴 \\n 시퀀스를 실제 줄 바꿈으로 바꾸십시오:

평소와 같이 콘텐츠를 내보내십시오.
텍스트 편집기에서 내보낸 파일을 여십시오.
리터럴 \n 시퀀스의 모든 인스턴스를 실제 줄 바꿈으로 바꾸십시오.
파일을 다시 가져오십시오.

앱 내 검색 및 바꾸기는 실제 줄 바꿈 삽입을 지원하지 않으므로, 이 바꾸기 작업은 파일을 다시 가져오기 전에 외부 텍스트 편집기에서 수행해야 합니다.