Did You Know? How to Use Flags When Pushing Content to Transifex with the JavaScript SDK

Hi everyone! I’m Sandy, and today I’ll share how to optimize your workflow using flags in the Transifex JavaScript SDK. These flags help you control what gets pushed, tag management, and even simulate changes before committing. Let’s explore how to use them!

Key Command Flags

  1. –verbose: Enables detailed logging during the push. This flag provides in-depth details on the process, perfect for debugging or tracking large uploads.

    • Example:
      txjs-cli push --verbose
      

    This will show every step the SDK takes, helping you identify any issues during the push.

  2. –append-tags: Adds new tags to strings without removing existing ones. If you want to add a new tag like “release_v1” to strings that already have other tags (e.g., “urgent”), this flag allows you to append without overwriting the current tags. It’s perfect for maintaining both old and new categorizations of content.

    • Example:
      Suppose you have a string tagged as “urgent” for critical messages:

      t('Contact support', { _tags: 'urgent' });
      

      Now, you want to mark it as part of your new release but still keep the “urgent” tag intact. You would run:

      txjs-cli push --append-tags="release_v1"
      

      After running the command, the string will have both the “urgent” and “release_v1” tags, ensuring it stays correctly categorized across different workflows.

  3. –dry-run: Simulates the push without making changes. This is your “preview mode.” It lets you check what will be pushed before any real changes happen in Transifex.

    • Example:
      txjs-cli push --dry-run
      

    Use this to see which strings will be uploaded without committing anything to Transifex.

  4. –with-tags-only: This flag allows you to push only the strings tagged with a specific value. It’s perfect when you’re working with staged releases, or when you want to prioritize content that’s tagged for a particular feature or purpose.

    • Example:
      Imagine you have the following strings in your project:
      t('Contact us', { _tags: 'important' });
      t('Learn more', { _tags: 'footer' });
      
      Running this command:
     txjs-cli push --with-tags-only="important"
    

    Only the “Contact us” string (tagged “important”) will be pushed to Transifex, while “Learn more” (tagged “footer”) will be excluded. This helps when you want to focus on uploading specific parts of your content, such as urgent updates or staged features.

  5. –purge: Removes content in Transifex that no longer exists in your local files. Over time, your codebase evolves, and you may remove or replace strings. The --purge flag ensures your Transifex project stays clean by removing outdated strings that no longer exist in your local files. This keeps your translations in sync with your current content.

    • Example:
      Let’s say your project initially had these strings:

      t('hello');
      t('goodbye');
      

      Now, you’ve refactored your code, replacing them with:

      t('welcome');
      t('farewell');
      

      By running:

      txjs-cli push --purge
      

      The new strings “welcome” and “farewell” will be pushed to Transifex, while the old “hello” and “goodbye” will be removed, ensuring that only the relevant strings remain in your Transifex project.

  6. –parser: Specifies the parser used for localization files (e.g., i18next).
    This flag ensures that Transifex processes your files correctly based on their format, reducing parsing errors during uploads.

    • Example:
      txjs-cli push --parser=i18next
      

Real-Life Use Case Example

Imagine you’re launching a new feature and need to push only strings tagged “release_v2.” You also want to clean up outdated strings from your project. Here’s how you’d do it:

txjs-cli push --with-tags-only="release_v2" --purge --verbose

This does three things:

  • Pushes only strings tagged with “release_v2.”
  • Removes outdated content in Transifex that no longer exists in your local files.
  • Provides detailed logs throughout the process for easy monitoring.

Conclusion

These flags give you precise control over how your content is uploaded to Transifex, making your workflow more efficient. Whether you need to append tags, simulate a push, or clean up old content, these tools ensure you’re always in control of your localization process.

For more detailed information, check out the official Transifex documentation.