.XCSTRINGS - Apple Strings Catalog (Strings)

本コンテンツはPhrase Language AIの機械翻訳により、英語から翻訳されています。

ファイル拡張子	.xcstrings
API拡張	strings_catalog
インポート	はい
エクスポート	はい
複数形のサポート	はい
説明のサポート	はい
フォーマットオプションファイルがアップロードまたはダウンロードされるときに指定できるオプションです。アップロード/ダウンロード方法（API、CLI、リポジトリ同期など）に応じて、クエリパラメータ`アップロード`、`ダウンロード`、または`phrase.yml`設定ファイルに指定できます。	convert_placeholder default_extraction_state

Apple Strings Catalog (.xcstrings) は、Xcode 15で導入されたローカリゼーション形式です。これは、複数形、デバイス固有のバリエーションなどを処理するための構造化された形式をサポートすることで、開発者がローカライズされた文字列を管理する方法を向上させます。この形式は、iOSおよびmacOSアプリケーションのローカリゼーション管理に推奨されるアプローチになりつつあります。

コメント、抽出状態、および翻訳すべきメタデータフィールドは、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設定ファイルにターゲットファイルを1つだけ指定します。
ロケールIDパラメータを使用して、エクスポートに含まれるすべての言語ロケールをリストします。

例 .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デバイスのために、Phrase Stringsに%lld 商品が注文されました|==|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": "%@ 日"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ 日"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version":"1.0"
}

ファイル形式オプション

識別子	convert_placeholder
タイプ	ブール
アップロード	いいえ
ダウンロード	はい
デフォルト	false
概要	プレースホルダーは、特定のフォーマット要件に一致するように変換されます。例：`$s`→`$@`、`%s`→`%@`

識別子	default_extraction_state
タイプ	文字列
アップロード	いいえ
ダウンロード	はい
デフォルト	null
概要	キーに既に抽出状態が定義されていない場合に、エクスポートされたファイルのキーに書き込まれる`extractionState`値を定義します。キーに既に`extractionState`が含まれている場合、その値はエクスポート中に保持されます。対応可能： UIダウンロード API CLI（`.phrase.yml`構成経由）およびリポジトリ同期