.XCSTRINGS - Apple Strings Catalog (Strings)

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

파일 확장명	.xcstrings
API 확장	strings_catalog
가져오기	예
내보내기	예
복수형 지원	예
설명 지원	예
형식 옵션 파일이 업로드되거나 다운로드될 때 지정할 수 있는 옵션입니다. 업로드/다운로드 방법(API, CLI, Repo sync 등)에 따라, `업로드`, `다운로드` 또는 `phrase.yml` 구성 파일의 쿼리 매개변수로 지정할 수 있습니다.	convert_placeholder default_extraction_state

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

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

Phrase는 또한 가져오는 동안 Xcode 번역 상태를 가장 가까운 Strings 동등물에 매핑하고 내보낼 때 Xcode 호환 값으로 다시 변환합니다. 특정 매핑이 적용되지 않으면, 번역됨이 기본 내보내기 값으로 사용됩니다. 필요한 경우, 상태 매핑을 건너뛰기 위해 가져올 때 번역 상태 무시 옵션을 사용하십시오.

코드 샘플

{
  "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를 사용할 때, 파일 내보내기는 .phrase.yml 구성 파일에 정의된 구조를 따릅니다. 풀 작업 중에 여러 언어가 단일 .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 파일을 가져올 때, 장치 유형이 이 구분자를 사용하여 기본 키 이름에 추가됩니다.

사례

%lld 제품(들) 주문됨이라는 키는 applewatch 장치에 대해 %lld 제품(들) 주문됨|==|device.applewatch라는 복수형 키로 Phrase Strings에 가져옵니다.

내보내기 중에, 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",
                      "값": "%@ 일"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "값": "%@ 일들"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": "1.0"
}

형식 옵션

식별자	convert_placeholder
유형	부울
업로드	아니요
다운로드	예
기본값	false
설명	자리 표시자는 일치 항목 형식의 특정 요구 사항으로 변환됩니다. 예: `$s`→`$@`, `%s`→`%@`

식별자	default_extraction_state
유형	문자열
업로드	아니요
다운로드	예
기본값	null
설명	키에 이미 정의된 추출 상태가 없을 때 내보내기 파일의 키에 기록되는 `extractionState` 값을 정의합니다. 키에 이미 `extractionState`가 포함되어 있으면, 내보내기 중에 그 값이 보존됩니다. 지원됨: UI 다운로드 API CLI (via `.phrase.yml` 구성) 및 Repo Sync