.XCSTRINGS - Apple Strings Catalog (Strings)

O conteúdo de toda a Central de Ajuda é traduzido automaticamente de inglês pelo Phrase Language AI.

Extensões de arquivo	.xcstrings
Extensão de API	strings_catalog
Importar	Sim
Exportar	Sim
Suporte para formas plurais	Sim
Suporte para descrição	Sim
Opções de formato Estas opções que podem ser especificadas quando um arquivo é feito upload e/ou Download. Dependendo do método de upload/Download (API, CLI, sincronização de repositório, etc.), elas podem ser especificadas em parâmetros de consulta `Upload`, `Download` ou no arquivo de configuração `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Apple Strings Catalog (.xcstrings) é um formato de localização introduzido no Xcode 15. Ele aprimora a maneira como os desenvolvedores gerenciam Strings localizadas, oferecendo suporte a formatos estruturados para lidar com pluralização, variações específicas de dispositivo e muito mais. Este formato está se tornando a abordagem recomendada para gerenciar localizações em aplicativos iOS e macOS.

Os campos de metadados comentar, extractionState e shouldTranslate são importados e exportados na ordem de pedido necessária para garantir a compatibilidade com o Xcode.

O Phrase também mapeia estados de tradução do Xcode para os equivalentes de Strings mais próximos durante a importação e os converte de volta para valores compatíveis com o Xcode na exportação. Se nenhum mapeamento específico se aplicar, translated é usado como o valor de exportação padrão. Se necessário, usar a opção Ignore translation state on import para ignorar o mapeamento de estado.

Amostra de código

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

Ao usar o Phrase CLI, as exportações de arquivo seguem a estrutura definida no arquivo de configuração .phrase.yml. Para garantir que vários idiomas sejam exportados para um único arquivo .XCSTRINGS durante operações de pull:

Especifique apenas uma tradução de arquivo no arquivo de configuração CLI.
Usar o parâmetro locale_ids para listar todos os locais de idioma incluídos na exportação.

Exemplo de configuração .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

Variações de dispositivo

Apple Strings Catalog oferece suporte a variações de dispositivo, que permitem conteúdos de tradução diferentes para a mesma chave, dependendo do dispositivo Apple que está sendo usado.

Para lidar com variações de dispositivo no Phrase Strings, chaves separadas são criadas para cada dispositivo usando o separador |==|. Ao importar arquivos .XCSTRINGS, o tipo de dispositivo é adicionado ao nome da chave base usando este separador.

Exemplo

A chave chamada %lld Product(s) Ordered para o dispositivo applewatch é importada como uma chave plural chamada %lld Product(s) Ordered|==|device.applewatch para o Phrase Strings.

Durante a exportar, Phrase Strings detecta a variante do dispositivo usando o separador e restaura sua estrutura aninhada original para o formato de localização da 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é"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substituições de string

O Apple Strings Catalog suporta substituições de string que fornecem marcadores de posição flexíveis para conteúdo dinâmico.

Para lidar com substituições de string no Phrase Strings, chaves separadas são criadas usando o separador |==|. Ao importar arquivos .XCSTRINGS, a substituição é adicionada ao nome da chave base usando este separador.

Phrase Strings também suporta a criação de Strings de substituição diretamente no projeto. Quando estruturas de substituição são criadas manualmente, uma chave base e uma chave de substituição correspondente devem ser definidas para garantir que o formato aninhado correto seja gerado durante a exportar.

Substituições sempre exigem um formato de nomeação de chave específico: keyName|==|substitution.[specifier].

Exemplo: Importando estruturas de substituição de arquivos .XCSTRINGS existentes

A chave chamada birdSightingAlert para a substituição BIRDS é importada como uma chave de plural chamada birdSightingAlert|==|substitution.BIRDS para o Phrase Strings.

Durante a exportar, Phrase Strings detecta a substituição usando o separador e restaura sua estrutura aninhada original para o formato de localização da 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"
                }
              }
            }
          }
        }
      }
    }
  }

Exemplo: Criando Strings de substituição do zero

Chave base

Uma chave base chamada keyName representa a string de formato de nível superior que contém o marcador de posição de substituição %#@format@.

Quando exportada, esta chave é escrita como a stringUnit primária para a entrada:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Chave de substituição

Uma string de substituição é definida como uma chave separada usando o formato de nomeação de substituição: keyName|==|substitution.li.

Esta chave contém o texto de substituição, normalmente com variações de plural. Durante a exportar, Phrase Strings detecta a substituição usando o separador |==|substitution. e restaura a estrutura aninhada correspondente sob a chave base:

{
  "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": "%@ dias"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": "1.0"
}

Opções de formato

Identificador	convert_placeholder
Tipo	Booleano
Upload	Não
Download	Sim
Padrão	false
Descrição	O marcador de posição será convertido para atender aos requisitos específicos do formato. Exemplo: `$s`→`$@`, `%s`→`%@`

Identificador	default_extraction_state
Tipo	string
Upload	Não
Download	Sim
Padrão	nulo
Descrição	Define o valor de `extractionState` gravado nas chaves no arquivo exportar quando nenhum estado de extração já está definido na chave. Se uma chave já contiver um `extractionState`, seu valor será preservado durante a exportar. Aceita: Downloads da interface do usuário API CLI (via configuração `.phrase.yml`) e Sincronização de Repositório

Identificador	locale_code_mapping
Tipo	object
Upload	Sim
Baixar	Sim
Padrão	{}
Descrição	Mapeia códigos de local do Phrase para os códigos de local gravados no arquivo .XCSTRINGS. Cada chave é o código de local do Phrase; cada valor é o código gravado no arquivo, por exemplo: { "en": "en-GB", "fr": "fr-FR" } No download, o Phrase reescreve o campo `sourceLanguage` e qualquer chave de `localizations` que corresponda a uma chave de mapeamento para o valor mapeado. Códigos sem um mapeamento permanecem inalterados. No upload, o Phrase aplica o mesmo mapeamento de forma inversa e converte os códigos de local do arquivo de volta para os códigos de local do Phrase correspondentes, incluindo `sourceLanguage`. Esta opção afeta apenas os códigos de local lidos e gravados no próprio arquivo .XCSTRINGS. O mapeamento de local baseado em nome de arquivo, usado por exemplo em padrões de nomenclatura de arquivos de integração com Git, é uma configuração separada que mapeia caminhos de arquivo em vez dos códigos dentro do .XCSTRINGS.