.XCSTRINGS - Apple Strings Catalog (Strings)

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

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

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

주석<1>, extractionState<2> 및 shouldTranslate<3> 메타데이터 필드는 Xcode와의 호환성을 보장하기 위해 필요한 순서대로 가져오기 및 내보내기됩니다.

Phrase는 또한 가져오기 중에 Xcode 번역 상태를 가장 가까운 Strings 대응 항목으로 매핑하고 내보내기 시 이를 다시 Xcode 호환 값으로 변환합니다. 특정 매핑이 적용되지 않는 경우 번역됨<1>이 기본 내보내기 값으로 사용됩니다. 필요한 경우 가져오기 시 번역 상태 무시 옵션을 사용하여 상태 매핑을 건너뜁니다.

코드 샘플

{
  "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": "1.0"
}

Phrase CLI<1>를 사용할 때 파일 내보내기는 .phrase.yml<2> 구성 파일에 정의된 구조를 따릅니다. 가져오기 작업 중에 여러 언어가 하나의 .XCSTRINGS 파일로 내보내지도록 하려면:

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

예시 .phrase.yml<3> 구성

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

<1>기기 변형

Apple Strings Catalog는 기기 변형을 지원하며, 이를 통해 사용 중인 Apple 기기에 따라 동일한 키에 대해 서로 다른 번역 내용을 허용합니다.

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

사례

applewatch<2> 기기에 대한 %lld Product(s) Ordered<1>라는 키는 Phrase Strings로 %lld Product(s) Ordered|==|device.applewatch<3>라는 복수형 키로 가져와집니다.

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

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indicates the number of products ordered, with device-specific variations",
      "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": "1.0"
}

형식 옵션

식별자	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 내부의 코드가 아닌 파일 경로를 매핑하는 별도의 설정입니다.