Skip to content

Home

Jump to bottom
Dmitry Studynsky edited this page Oct 10, 2025 · 17 revisions

Smartling CLI

A powerful command-line interface for the Smartling Translation Management Platform built in Go. Automate translation workflows, manage files, and leverage machine translation capabilities directly from your terminal.

Quick Start

  1. Install the CLI for your platform
  2. Configure your credentials: smartling-cli init
  3. Upload your first file: smartling-cli files push my-file.txt --job "My First Job"

Key Features

  • File Management: Upload, download, list, and organize translation files
  • Job-Based Workflows: Automatic job creation and management for translation projects
  • Machine Translation: Detect languages and translate content using Smartling's MT engine
  • Bulk Operations: Process multiple files with pattern matching and wildcards
  • Project Management: View project details, locales, and translation status
  • Flexible Configuration: Command-line flags, config files, and environment variables

What's New

The Smartling CLI continues to evolve with new features and improvements. For the latest release information, including new features, bug fixes, and breaking changes, see our GitHub Releases.

Key capabilities include:

  • Job-based file uploads for better organization and workflow management
  • Machine translation commands for language detection and translation
  • Enhanced configuration management with clear value hierarchy
  • File type override support for flexible file handling
  • Comprehensive command documentation optimized for automation

Installation

Choose your platform:

Documentation

Built-in Help

Access comprehensive help for any command:

smartling-cli --help
smartling-cli files push --help
smartling-cli mt translate --help

Initial Configuration

Create a configuration file with your Smartling API credentials:

smartling-cli init

This creates a smartling.yml file in your current directory with your project settings. Note: Running init again will overwrite the existing configuration file.

Configuration Hierarchy

The CLI uses the following priority order for configuration values:

  1. Command-line flags (highest priority)
  2. Configuration file values
  3. Environment variables
  4. Default values (fallback)

Core Commands

File Operations

# Upload files to a translation job
smartling-cli files push my-file.txt --job "Website Update" --authorize

# Upload multiple files with pattern matching
smartling-cli files push "src/**/*.json" --job "App Localization"

# Download translated files
smartling-cli files pull "**/*.json" --locale fr-FR --locale de-DE

# List project files
smartling-cli files list

# Check file status across locales
smartling-cli files status

Machine Translation

# Detect file language
smartling-cli mt detect document.txt

# Translate with automatic language detection
smartling-cli mt translate document.txt --target-locale es-ES

# Translate with explicit source language
smartling-cli mt translate document.txt --source-locale en --target-locale fr-FR

Project Management

# View project information
smartling-cli projects info

# List all target locales
smartling-cli projects locales

# List all projects in your account
smartling-cli projects list

Advanced Usage

Global Options

Override configuration values with command-line flags:

smartling-cli files list \
  --project "PROJECT_ID" \
  --account "ACCOUNT_ID" \
  --config "/path/to/config.yml"

Branching and Versioning

Organize files with branch prefixes:

# Manual branch naming
smartling-cli files push "**/*.txt" --branch "feature-branch"

# Automatic Git branch detection
smartling-cli files push "**/*.txt" --branch "@auto"

Pattern Matching

Use powerful glob patterns for bulk operations:

# All JSON files in subdirectories
smartling-cli files push "**/*.json"

# Specific file types
smartling-cli files push "**/*.{json,xml,properties}"

# Files matching naming convention
smartling-cli files push "**/messages_*.properties"

Breaking Changes

Version 2.2

Job-Based File Uploads: The files push command now creates translation jobs by default.

  • New behavior: All files upload to a Smartling job
  • Default job name: "CLI uploads" (if not specified)
  • Authorization: Jobs remain unauthorized unless --authorize flag is used
  • Locale targeting: Files added to all project locales unless --locale specified

Updated Command Format:

# New recommended format
smartling-cli files push <file> <uri> --job <job_name> [--authorize] [--locale <locale>]

# Legacy format still works but creates "CLI uploads" job
smartling-cli files push <file> <uri>

Version 2.1

Directory Flag Change: Global flag -d, --directory replaced with --operation-directory.

# Before (v2.0 and earlier)
smartling-cli -d /path/to/project [command]

# After (v2.1+)
smartling-cli --operation-directory /path/to/project [command]

Migration Guide

Upgrading to 2.2

Update file upload commands to use the new job-based workflow:

  1. Add job specification:

    # Before
smartling-cli files push my-file.txt

# After
smartling-cli files push my-file.txt --job "My Translation Job"

  2. Review locale targeting:

    # Target specific locales only
smartling-cli files push my-file.txt --job "My Job" --locale fr-FR --locale de-DE

  3. Enable automatic authorization if needed:

    smartling-cli files push my-file.txt --job "My Job" --authorize

Job reuse: CLI automatically reuses existing jobs with the same name. If a job is Canceled or Closed, a new job is created with a timestamp suffix.

Upgrading to 2.1

Update directory flags in scripts and automation:

# Replace all instances of -d or --directory
sed 's/--directory/--operation-directory/g' your-script.sh
sed 's/-d /--operation-directory /g' your-script.sh

Upgrading from 1.7

  1. Review command syntax - Major architectural changes in 2.0+
  2. Test existing workflows for compatibility
  3. Update configuration files to new YAML format if needed
  4. Check authentication setup with new credential hierarchy

For detailed compatibility information, see our GitHub releases.

Example Workflows

Find comprehensive examples for common use cases:

Error Handling

The CLI uses standard output streams:

  • stdout: Normal operation results and data
  • stderr: Error messages and diagnostic information

For troubleshooting, check our Breaking Changes section or review the GitHub issues.

Additional Resources

Clone this wiki locally