Каталоги Xcode .xcstrings

Что такое каталоги Xcode .xcstrings?

Каталоги Xcode .xcstrings — это современный формат локализации от Apple, представленный в Xcode 15. Они хранят все локализации в одном JSON-файле, поддерживая плюрализацию, вариации для устройств и метаданные перевода.

Например:

{
  "sourceLanguage" : "en",
  "strings" : {
    "item_count" : {
      "comment" : "Количество элементов, отображаемых в списке — поддерживает плюрализацию",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "1 элемент"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%d элементов"
                }
              },
              "zero" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "Нет элементов"
                }
              }
            }
          }
        }
      }
    },
    "welcome_message" : {
      "comment" : "Приветственное сообщение, отображаемое на главном экране приложения",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Привет, мир!"
          }
        }
      }
    }
  }
}

Что такое Lingo.dev CLI?

Lingo.dev CLI — это бесплатный инструмент с открытым исходным кодом для перевода приложений и контента с помощью ИИ. Он разработан для замены традиционного программного обеспечения для управления переводами, интегрируясь с существующими конвейерами.

Чтобы узнать больше, см. Обзор.

О данном руководстве

В этом руководстве объясняется, как переводить файлы Xcode .xcstrings с помощью Lingo.dev CLI.

Вы узнаете, как:

Создать проект с нуля
Настроить конвейер перевода
Генерировать переводы с помощью ИИ

Предварительные требования

Для использования Lingo.dev CLI убедитесь, что установлена версия Node.js v18+:

❯ node -v
v22.17.0

Шаг 1. Настройка проекта

В каталоге вашего проекта создайте файл i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Этот файл определяет поведение конвейера перевода, включая языки для перевода и расположение локализуемого контента в файловой системе.

Чтобы узнать больше о доступных свойствах, см. i18n.json.

Шаг 2. Настройка исходной локали

Исходная локаль — это оригинальный язык и регион, на которых был написан ваш контент. Чтобы настроить исходную локаль, задайте свойство locale.source в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Исходная локаль должна быть указана в виде языкового тега BCP 47.

Для полного списка кодов локалей, поддерживаемых Lingo.dev CLI, см. Поддерживаемые коды локалей.

Шаг 3. Настройка целевых локалей

Целевые локали — это языки и регионы, на которые вы хотите перевести ваш контент. Чтобы настроить целевые локали, задайте свойство locale.targets в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Шаг 4. Создание исходного контента

Если вы еще этого не сделали, создайте файл .xcstrings, содержащий контент для перевода.

Примечание: В процессе перевода исходные файлы контента будут перезаписаны, чтобы включить переведенный контент (в дополнение к исходному контенту).

Шаг 5. Создание корзины

В файле i18n.json добавьте объект "xcode-xcstrings" в объект buckets:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "xcode-xcstrings": {}
  }
}

В объекте "xcode-xcstrings" определите массив из одного или нескольких шаблонов include:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "xcode-xcstrings": {
      "include": ["./example.xcstrings"]
    }
  }
}
```
Эти шаблоны определяют, какие файлы переводить, и могут:
- указывать на конкретные пути к файлам (например, "some/dir/file.xcstrings")
- использовать звездочки в качестве подстановочных символов (например, "some/dir/*.xcstrings")
Рекурсивные шаблоны с глобами (например, **/*.xcstrings) не поддерживаются.

Шаг 6. Настройка LLM

Lingo.dev CLI использует большие языковые модели (LLM) для перевода контента с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы начать как можно быстрее, мы рекомендуем использовать Lingo.dev Engine — нашу собственную платформу, которая предоставляет 10 000 токенов бесплатного ежемесячного использования:

Зарегистрируйтесь в Lingo.dev.
Выполните следующую команду:
```
npx lingo.dev@latest login
```
Эта команда откроет ваш браузер по умолчанию и попросит вас пройти аутентификацию.
Следуйте инструкциям.

Шаг 7. Генерация переводов

В каталоге, содержащем файл i18n.json, выполните следующую команду:

npx lingo.dev@latest run

Эта команда:

Считывает файл i18n.json.
Находит файлы, которые нужно перевести.
Извлекает переводимый контент из файлов.
Использует настроенную LLM для перевода извлеченного контента.
Записывает переведенный контент обратно в файловую систему.

При первом создании переводов создается файл i18n.lock. Этот файл отслеживает, какой контент был переведен, предотвращая ненужные повторные переводы при последующих запусках.

Пример

example.xcstrings (до перевода)

{
  "sourceLanguage" : "en",
  "strings" : {
    "welcome_message" : {
      "comment" : "Приветственное сообщение, отображаемое на главном экране приложения",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Hello, world!"
          }
        }
      }
    },
    "item_count" : {
      "comment" : "Количество элементов - поддерживает множественное число",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "zero" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "Нет элементов"
                }
              },
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "1 элемент"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%d элемента"
                }
              }
            }
          }
        }
      }
    }
  }
}

example.xcstrings (после перевода)

{
  "sourceLanguage" : "en",
  "strings" : {
    "welcome_message" : {
      "comment" : "Приветственное сообщение, отображаемое на главном экране приложения",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Hello, world!"
          }
        },
        "ru" : {
          "stringUnit" : {
            "state" : "translated",
            "value" : "Привет, мир!"
          }
        }
      }
    },
    "item_count" : {
      "comment" : "Количество элементов - поддерживает множественное число",
      "extractionState" : "manual",
      "localizations" : {
        "en" : {
          "variations" : {
            "plural" : {
              "zero" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "No items"
                }
              },
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "1 item"
                }
              },
              "other" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%d items"
                }
              }
            }
          }
        },
        "ru" : {
          "variations" : {
            "plural" : {
              "zero" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "Нет элементов"
                }
              },
              "one" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "1 элемент"
                }
              },
              "few" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%d элемента"
                }
              },
              "many" : {
                "stringUnit" : {
                  "state" : "translated",
                  "value" : "%d элементов"
                }
              }
            }
          }
        }
      }
    }
  }
}

i18n.json

{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["ru"]
  },
  "buckets": {
    "xcode-xcstrings": {
      "include": ["./example.xcstrings"]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}

i18n.lock

version: 1
checksums:
  d3330df55a54ce785f378e7388282a96:
    welcome_message: 57da71b2c89eaddcbca81b3c3766deed
    item_count/zero: 955c31a42e9ff663a49e69e944c8c537
    item_count/one: 154c8eed472b867c8d5af66d162abd2c
    item_count/other: ecb3f18dc6a5e7b3e1d9afe7ef62cf07
  614e9d20c639fed18ee30b9f9637c83d:
    item_count/one: d25ee41f72a2ea94ebc6debc85b9e573
    item_count/other: ecb3f18dc6a5e7b3e1d9afe7ef62cf07
    item_count/zero: 955c31a42e9ff663a49e69e944c8c537
    welcome_message: 0468579ef2fbc83c9d520c2f2f1c5059