@owowagency/wordsmith-cli

Wordsmith CLI

• Usage
  • NPM
  • Composer
  • Github actions
• Commands
  • List projects
  • Pull
  • Push
• Configuration
  • Top level
  • Targets
  • Supported formats
• Example configuration

Usage

NPM

You can use the CLI using npx or by installing it with your preferred package manager:

npx @owowagency/wordsmith-cli --help

# npm
npm install -g @owowagency/wordsmith-cli
# yarn
yarn global add @owowagency/wordsmith-cli
# pnpm
pnpm install -g @owowagency/wordsmith-cli

wordsmith --help

You can also install it per project and use it as a script:

# npm
npm install @owowagency/wordsmith-cli
# yarn
yarn add @owowagency/wordsmith-cli
# pnpm
pnpm install @owowagency/wordsmith-cli

Then add the following to your package.json:

{
    "scripts": {
        "wordsmith": "wordsmith"
    }
}

Composer

To use the CLI using composer, install it using:

composer require owowagency/wordsmith-cli

Then add the following to your composer.json:

{
    "scripts": {
        "wordsmith": "wordsmith"
    }
}

composer wordsmith -- --help

Github actions

To use the CLI in Github actions, use the wordsmith-action

Commands

List Projects

Lists all projects in the scope of the access token, which can be configured in wordsmith.yml, see Configuration

wordsmith list-projects --env=wordsmith.yml

short	long	type	default	description
-e	--env	String	wordsmith.yml	Path to the configuration file
	--access-token	String	wordsmith.yml	Access token
	--verbose	Bool	false	Enables verbose logging

Pull

Pulls translation files from the API, translation files can be configured in wordsmith.yml, see Configuration

wordsmith pull --env=wordsmith.yml

short	long	type	default	description
-e	--env	String	wordsmith.yml	Path to the configuration file
	--access-token	String	wordsmith.yml	Access token
	--verbose	Bool	false	Enables verbose logging

Push

Pushes translation files to the API, translation files can be configured in wordsmith.yml, see Configuration

wordsmith push --env=wordsmith.yml --force --verify

short	long	type	default	description
-e	--env	String	wordsmith.yml	Path to the configuration file
	--access-token	String	wordsmith.yml	Access token
-f	--force	Bool	false	Overwrite existing translations
-v	--verify	Bool	false	Verify pushed translations
	--verbose	Bool	false	Enables verbose logging

Configuration

Wordsmith CLI accepts YAML configuration files, the default configuration file is wordsmith.yml but can be overwritten using the --env flag on push and pull commands

Top level

name	type	description
project-id	Number	ID of the project
token	String	Access token or environment variable for access token, default: ${{ WORDMSMITH_ACCESS_TOKEN }}
targets	Target[]	See Targets

Targets

Any remaining properties will be passed on to the API when pushing or pulling.

name	type	description
file	String	Path to the translation file, {locale} will be replaced with the locale e.g. values-{locale}/strings.xml will become values-en/strings.xml
default-locale-override	String?	Path override for the default locale, this may be useful on Android where the default strings are stored in values/ instead of values-{locale}/
locales	String[]	Locales to pull/push, defaults to existing project locales
types	(pull | push)[]	Enables push and/or pull for this target
file-type	String	The file format of the translation file, see Supported formats
tags	String[]	Pull only translations with given tags or attach tags to pushed translations, defaults to []

Supported formats

• apple-strings (iOS)
• android-strings (Android xml)
• json
• csv
• i18next (i18next)
• po (Gettext)
• apple-xliff
• angular-xliff
• symfony-xliff

Example Configuration

project-id: 1
# Use "${{ ENV_VARIABLE_NAME }}" to use environment variables (recommended)
# Access tokens can also be stored in the config file directly (not recommended)
# Defaults: ${{ WORDSMITH_ACCESS_TOKEN }}
token: ${{ WORDSMITH_ACCESS_TOKEN }}
targets:
    # The file to use when pulling/pushing, {locale} will be replaced by the pulled/pushed locale, e.g. locales/values-en/strings-web.xml
  - file: locales/values-{locale}/strings-app.xml
    # [Optional] The file to use when pulling/pushing the default locale
    default-locale-override: locales/values/strings-app.xml
    # Types of this target, possible values: push, pull
    types:
      - push
      - pull
    # Format of the file, possible values:
    # - apple-strings (iOS Localizable string files)
    # - android-strings (XML Android string files)
    # - csv
    # - i18next
    # - json
    file-type: android-strings
    # [Optional] tags to include when pulling/pushing this file
    tags:
      - app
  - file: locales/values-{locale}/strings-library.xml
    default-locale-override: locales/values/strings-library.xml
    types:
      - push
      - pull
    file-type: android-strings
    tags:
      - library