{"id":31898268,"url":"https://github.com/onthegosystems/ptc-cli","last_synced_at":"2025-10-13T11:56:42.811Z","repository":{"id":310474654,"uuid":"1038449669","full_name":"OnTheGoSystems/ptc-cli","owner":"OnTheGoSystems","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-29T07:51:15.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-29T11:31:15.561Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OnTheGoSystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-15T08:09:17.000Z","updated_at":"2025-08-29T07:51:19.000Z","dependencies_parsed_at":"2025-08-18T11:35:09.585Z","dependency_job_id":"250ed889-b8e0-45d8-9a39-c55c3f7241a0","html_url":"https://github.com/OnTheGoSystems/ptc-cli","commit_stats":null,"previous_names":["onthegosystems/ptc-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/OnTheGoSystems/ptc-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OnTheGoSystems%2Fptc-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OnTheGoSystems%2Fptc-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OnTheGoSystems%2Fptc-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OnTheGoSystems%2Fptc-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OnTheGoSystems","download_url":"https://codeload.github.com/OnTheGoSystems/ptc-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OnTheGoSystems%2Fptc-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014820,"owners_count":26085596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T11:56:33.531Z","updated_at":"2025-10-13T11:56:42.804Z","avatar_url":"https://github.com/OnTheGoSystems.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PTC CLI - Private Translation Cloud CLI\n\nBash script for processing translation files through PTC (Private Translation Cloud) API with support for various project configurations.\n\n[Sample repositories](https://github.com/OnTheGoSystems/ptc-cli/wiki/Sample-repositories)\n\n## Features\n\n- 🔍 Flexible file search using globbing or explicit file configuration\n- 🛡️ Strict error handling for CI environments\n- 📝 Detailed logging with color highlighting\n- ⚡ Optimized for CI/CD usage\n- 🔄 Step-based processing (Upload → Process → Monitor → Download)\n- 🎯 Isolated action support (upload, status, download)\n- 📊 Compact progress monitoring with status indicators\n- 🗂️ YAML configuration file support\n- 📋 Additional translation files support (mo, php, json, etc.)\n\n## Quick Start\n\n### Using Configuration File (Recommended)\n\n```bash\n# Create config file\ncat \u003e .ptc-config.yml \u003c\u003c 'EOF'\nsource_locale: en\n\nfiles:\n  - file: src/locales/en.json\n    output: src/locales/{{lang}}.json\n  \n  - file: languages/plugin.pot\n    output: languages/plugin-{{lang}}.po\n    additional_translation_files:\n      - type: mo\n        path: languages/plugin-{{lang}}.mo\n      - type: po\n        path: languages/plugin-{{lang}}.po\nEOF\n\n# Process translations with token from command line\n./ptc-cli.sh --config-file .ptc-config.yml --api-token=\"$PTC_API_TOKEN\"\n```\n\n### Using Patterns\n\nConvenient for processing multiple files when the file or path to it contains a language code. In this case, you cannot transfer additional translation files (e.g. `mo`, `po`) or configure the output_file_path for each.\n\n```bash\n# Make script executable\nchmod +x ptc-cli.sh\n\n# Find files for English language by pattern\n./ptc-cli.sh --source-locale en --patterns 'sample-{{lang}}.json' --api-token=your-token\n\n# Find files in subdirectories\n./ptc-cli.sh --source-locale en --patterns '{{lang}}/**/*.json' --api-url=https://app.ptc.wpml.org/api/v1/\n\n# Multiple patterns\n./ptc-cli.sh -s en -p 'sample-{{lang}}.json,{{lang}}-*.properties' --api-token=your-token\n```\n\n## Usage\n\n### Main Options\n\n**File Selection:**\n- `-c, --config-file FILE` - YAML configuration file (recommended)\n- `-p, --patterns PATTERNS` - File patterns separated by commas\n\n**Basic Parameters:**\n- `-s, --source-locale LOCALE` - Source language (required unless in config)\n- `-t, --file-tag-name TAG` - File tag name/branch name (default: auto-detect from git)\n- `-d, --project-dir DIR` - Project directory (default: current)\n\n**API Configuration:**\n- `--api-url URL` - PTC API base URL (default: https://app.ptc.wpml.org/api/v1/)\n- `--api-token TOKEN` - API authentication token\n- `--monitor-interval SECONDS` - Status check interval (default: 5)\n- `--monitor-max-attempts COUNT` - Maximum monitoring attempts (default: 100)\n\n**Control Options:**\n- `--action ACTION` - Perform isolated action: upload, status, download\n- `-v, --verbose` - Verbose output\n- `-n, --dry-run` - Show what would be done without executing\n- `-h, --help` - Show help\n- `--version` - Show version\n\n## Configuration File Format\n\nThe YAML configuration file supports full project setup:\n\n```yaml\n# Basic settings\nsource_locale: en\nfile_tag_name: main\napi_url: https://app.ptc.wpml.org/api/v1/\n# api_token: NEVER store API tokens in config files committed to repository!\n# Use --api-token parameter or PTC_API_TOKEN environment variable instead\n\n# Monitoring settings (optional)\nmonitor_interval: 5\nmonitor_max_attempts: 100\n\n# Files to translate\nfiles:\n  # React app localization files\n  - file: src/locales/en.json\n    output: src/locales/{{lang}}.json\n    additional_translation_files:\n      - type: mo\n        path: dist/locales/{{lang}}.mo\n      - type: php\n        path: includes/lang-{{lang}}.php\n  \n  # Admin panel translations  \n  - file: admin/locales/en.json\n    output: admin/locales/{{lang}}.json\n  \n  # WordPress plugin translations\n  - file: languages/plugin.pot\n    output: languages/plugin-{{lang}}.po\n    additional_translation_files:\n      - type: mo\n        path: languages/plugin-{{lang}}.mo\n      - type: json\n        path: languages/plugin-{{lang}}-wp.json\n```\n\n### Usage Examples\n\n**With Configuration File:**\n```bash\n# Basic usage with config\n./ptc-cli.sh --config-file config.yml\n\n# Dry run to see what would happen\n./ptc-cli.sh -c config.yml --dry-run --verbose\n\n# Override specific settings\n./ptc-cli.sh -c config.yml --api-token=different-token --file-tag-name=feature-branch\n\n# Isolated actions\n./ptc-cli.sh -c config.yml --action upload                   # Only upload files\n./ptc-cli.sh -c config.yml --action status --verbose         # Check translation status\n./ptc-cli.sh -c config.yml --action download                 # Download completed translations\n```\n\n**With params:**\n```bash\n# Basic usage\n./ptc-cli.sh -s en -p 'sample-{{lang}}.json' --api-token=your-token\n\n# Search in specific directory\n./ptc-cli.sh -s de -p '{{lang}}/**/*.json' -d /path/to/project\n\n# Dry run with verbose output\n./ptc-cli.sh -s en -p '{{lang}}/*.json' --verbose --dry-run --api-token=your-token\n\n# Multiple patterns\n./ptc-cli.sh -s en -p 'i18n/{{lang}}/app.json,locales/{{lang}}/*.properties' --api-token=your-token\n\n# WordPress WPSite example\n./ptc-cli.sh -s en -p 'languages/wpsite.pot' -t main --api-token=your-token\n\n# Isolated actions with patterns\n./ptc-cli.sh -s en -p 'sample-{{lang}}.json' --action upload --api-token=your-token\n./ptc-cli.sh -s en -p 'sample-{{lang}}.json' --action status --verbose --api-token=your-token\n./ptc-cli.sh -s en -p 'sample-{{lang}}.json' --action download --api-token=your-token\n```\n\n## Processing Workflow\n\nThe script supports two modes of operation:\n\n### Full Workflow (Default)\nThe script follows a step-based approach:\n\n1. **📤 Upload Step**: All files are uploaded to the PTC API\n2. **⚙️ Processing Step**: Translation processing is triggered for all files  \n3. **👀 Monitoring Step**: Translation status is monitored with compact progress display\n4. **📥 Download Step**: Completed translations are downloaded and unpacked\n\n### Isolated Actions\nFor more granular control, you can perform specific steps in isolation:\n\n#### `--action upload`\nOnly uploads files to PTC without starting translation processing.\n```bash\n./ptc-cli.sh -c config.yml --action upload\n```\n\n#### `--action status`\nChecks the translation status of files without downloading.\n```bash\n./ptc-cli.sh -c config.yml --action status --verbose\n```\n\n#### `--action download`\nDownloads completed translations without checking or uploading.\n```bash\n./ptc-cli.sh -c config.yml --action download\n```\n\n**Use Cases for Isolated Actions:**\n- **CI/CD pipelines**: Upload files in one job, check status and download in another\n- **Manual workflows**: Upload files, review translations externally, then download\n- **Debugging**: Check specific status or retry downloads without re-uploading\n\n### Progress Indicators\n\nDuring monitoring, you'll see compact status indicators (Each letter for one file):\n\n- `UU 12/30` - Unknown status (12 attempts out of 30 total)\n- `QQ 23/30` - Queued for processing\n- `PP 25/30` - Processing in progress\n- `CQ 27/30` - Some completed, some queued\n- `CC 28/30` - All completed\n\n**Status Characters:**\n- 🟢 `C` - Completed\n- 🔵 `Q` - Queued\n- 🔵 `P` - Processing\n- 🔴 `F` - Failed\n- 🟡 `U` - Unknown\n\n## CI/CD Usage\n\n### GitHub Actions\n\nAdd PTC_API_TOKEN to the repository secrets (Settings -\u003e Secrets and variables -\u003e Actions -\u003e New repository secret).\nEnsure to turn on the \"Allow GitHub Actions to create and approve pull requests\" permission in the repository settings (Settings -\u003e Actions -\u003e General -\u003e Workflow permissions).\n\n```yaml\nname: Process Translation Files\non:\n  workflow_dispatch: # Manual trigger\n\njobs:\n  process-translations:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n      pull-requests: write\n    \n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n      \n      - name: Setup PTC CLI\n        run: |\n          curl -fsSL https://raw.githubusercontent.com/OnTheGoSystems/ptc-cli/refs/heads/main/ptc-cli.sh -o ptc-cli.sh\n          chmod +x ptc-cli.sh\n      \n      - name: Process translations with PTC CLI\n        env:\n          PTC_API_TOKEN: ${{ secrets.PTC_API_TOKEN }}\n        run: |\n          ./ptc-cli.sh \\\n            --config-file .ptc/config.yml \\\n            --api-token ${{ secrets.PTC_API_TOKEN }} \\\n            --verbose\n      \n      - name: Clean up temporary files\n        run: |\n          rm -f ptc-cli.sh\n      \n      - name: Create Pull Request with translations\n        if: success()\n        uses: peter-evans/create-pull-request@v5\n        with:\n          token: ${{ secrets.GITHUB_TOKEN }}\n          commit-message: \"🌐 Update translations via PTC CLI\"\n          title: \"🌐 Update translations from PTC\"\n          body: |\n            ## 🌐 Translation Update\n            \n            This PR contains new translations processed by PTC CLI.\n            \n            **Triggered by:** ${{ github.event_name }}\n            **Branch:** ${{ github.ref_name }}\n            **Commit:** ${{ github.sha }}\n            \n            ---\n            *Auto-generated by GitHub Actions*\n          delete-branch: true\n```\n\nSample `.ptc/config.yml` file:\n\n```yaml\nsource_locale: en\nfile_tag_name: main\n\nfiles:\n  - file: src/locales/en.json\n    output: src/locales/{{lang}}.json\n```\n\n### GitLab CI\n\n```yaml\nprocess_translations:\n  stage: deploy\n  script:\n    - chmod +x ptc-cli.sh\n    - ./ptc-cli.sh -c config.yml --api-token=\"$PTC_API_TOKEN\" -v\n  variables:\n    PTC_API_TOKEN: \"$CI_PTC_API_TOKEN\"\n  only:\n    - merge_requests\n    - main\n```\n\n### Additional Translation Files\n\nWhen using YAML configuration, you can specify additional files to be generated (useful for WordPress):\n\n```yaml\nfiles:\n  - file: languages/plugin.pot\n    output: languages/plugin-{{lang}}.po\n    additional_translation_files:\n      - type: mo\n        path: languages/plugin-{{lang}}.mo\n      - type: json\n        path: languages/plugin-{{lang}}.json\n      - type: php\n        path: includes/lang-{{lang}}.php\n```\n\n### Troubleshooting\n\n**Common Issues:**\n\n1. **HTTP 401 Unauthorized**\n   ```bash\n   [ERROR] Failed to upload file: example.json (HTTP 401)\n   ```\n   - Check your API token\n   - Verify token has correct permissions\n\n2. **HTTP 403 Forbidden**\n   ```bash\n   [ERROR] Failed to upload file: example.json (HTTP 403)\n   ```\n   - Check your API token\n   - Check your Subscription\n   - Verify token has correct permissions\n\n3. **Files not found**\n   ```bash\n   [ERROR] No files found for pattern: {{lang}}.json\n   ```\n   - Check file paths in config\n   - Verify source locale matches your files\n   - Use `--verbose` to see search details\n\n5. **Translation timeout**\n   ```bash\n   [WARNING] Timed out files: 1\n   ```\n   - Increase `--monitor-max-attempts`\n   - Check translation status manually with provided curl command\n\n## Development\n\nSee [DEVELOPMENT.md](docs/DEVELOPMENT.md) for development and testing instructions.\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonthegosystems%2Fptc-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonthegosystems%2Fptc-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonthegosystems%2Fptc-cli/lists"}