.XCSTRINGS - Catálogo de Strings da Apple (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 Essas opções podem ser especificadas quando um arquivo é enviado e/ou baixado. 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

Catálogo de Strings da Apple (.xcstrings) é um formato de localização introduzido no Xcode 15. Ele melhora a forma como os desenvolvedores gerenciam strings localizadas, suportando formatos estruturados para lidar com pluralização, variações específicas de dispositivos e mais. Esse formato está se tornando a abordagem recomendada para gerenciar localizações em aplicativos iOS e macOS.

Os campos de metadados comentar, estadoDeExtração e deveTraduzir são importados e exportados na ordem necessária para garantir compatibilidade com o Xcode.

A Phrase também mapeia os estados de tradução do Xcode para os equivalentes mais próximos de Strings 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, traduzido é usado como o valor de exportação padrão. Se necessário, use a opção Ignorar estado de tradução na importação para pular o mapeamento de estado.

Amostra de código

{
  "sourceLanguage": "en",
  "strings": {
    "Aviso de Sincronização": {
      "comment": "Mensagem de função de sincronização indisponível",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "A sincronização em nuvem deve estar habilitada para usar este recurso."
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "La synchronisation cloud doit être activée pour utiliser cette fonction."
          }
        }
      }
    },
    "Chosen Collections": {
      "comment": "Título da visualização indicando coleções de fotos selecionadas",
      "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 Coleções Selecionadas"
                }
              }
            }
          }
        }
      }
    },
    "Settings Hub": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Centro de configuración"
          }
        }
      }
    }
  },
  "version": "1.0"
}

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

Especifique apenas um alvo de arquivo no arquivo de configuração do CLI.
Use o parâmetro locale_ids para listar todos os locais de idioma incluídos na exportação.

Exemplo .phrase.yml configuração

pull:
  targets:
    - file: ./i18n-test/Localizable.xcstrings
      params:
        locale_id: en # Idioma principal para o download
        locale_ids: # Idiomas adicionais a incluir
          - de
          - es
          - fr 
        file_format: strings_catalog

Variações de dispositivo

O Apple Strings Catalog suporta variações de dispositivo, que permitem diferentes conteúdos de tradução para a mesma chave, dependendo do dispositivo Apple em uso.

Para lidar com variações de dispositivo nas Strings do Phrase, 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 Produto(s) Pedido(s) para o dispositivo applewatch é importada como uma chave plural chamada %lld Produto(s) Pedido(s)|==|device.applewatch nas Strings do Phrase.

Durante a exportação, o 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 Produto(s) Pedido(s)": {
      "comment": "Indica o número de produtos pedidos, com variações específicas do dispositivo",
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "applewatch": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produto pedido (Apple Watch)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produtos pedidos (Apple Watch)"
                      }
                    }
                  }
                }
              },
              "ipad": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produto pedido (iPad)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produtos pedidos (iPad)"
                      }
                    }
                  }
                }
              },
              "iphone": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produto pedido (iPhone)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produtos pedidos (iPhone)"
                      }
                    }
                  }
                }
              },
              "mac": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produto pedido (Mac)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Produtos pedidos (Mac)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produto(s) pedido(s)"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produits commandés"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit commandé"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substituições de string

O Catálogo de Strings da Apple suporta substituições de string que fornecem espaços reservados flexíveis para conteúdo dinâmico.

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

Strings de Phrase também suportam 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 exportação.

Substituições sempre requerem um formato de nomenclatura 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 plural chamada birdSightingAlert|==|substitution.BIRDS nas Strings de Phrase.

Durante a exportação, as Strings de Phrase detectam a substituição usando o separador e restauram sua estrutura aninhada original para o formato de localização da Apple.

"birdSightingAlert": {
  "comment": "Mensagem de alerta indicando o número de pássaros avistados",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "new",
        "value": "Você avistou %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier": "BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "new",
                  "value": "a bird"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "new",
                  "value": "vários pássaros"
                }
              },
              "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 principal 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, tipicamente com variações plurais. Durante a exportação, 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": "%@ dia"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ dias"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": "1.0"
}

Opções de formato

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

Identificador	default_extraction_state
Tipo	string
Upload	Não
Baixar	Sim
Padrão	nulo
Descrição	Define o valor de `extractionState` escrito nas chaves no arquivo exportado quando nenhum estado de extração já está definido na chave. Se uma chave já contém um `extractionState`, seu valor é preservado durante a exportação. Aceito em: downloads da interface do usuário API CLI (via `.phrase.yml` configuração) e Sincronização de Repositório