GettextOps.Operations.ChangeMsgid (gettext_ops v0.1.1)

View Source

Change msgid operation for updating source text across all .po and .pot files.

This module provides functionality to update msgid (source text) across all locale .po files and .pot template files while preserving existing translations.

Important: This operation updates the source text (msgid) but keeps all translations (msgstr) intact. It updates:

  • All locale .po files (e.g., priv/gettext/sv/LC_MESSAGES/default.po)
  • The .pot template file (e.g., priv/gettext/default.pot)

Use Cases

This command is useful when you need to:

  • Fix typos in source strings
  • Improve wording of UI text
  • Standardize terminology
  • Refactor text keys

Atomic Updates

Updates are performed atomically by writing to a temporary file and then renaming it to the original file. This prevents corruption if the operation fails midway.

Options

  • :domain - The domain to update (defaults to configured default_domain)
  • :dry_run - Preview changes without modifying files (default: false)

Examples

# Update msgid across all files
{:ok, result} = GettextOps.Operations.ChangeMsgid.run("Sign In", "Log In")
# => {:ok, %{files_updated: 3, entries_updated: 3, changes: [...]}}

# Preview changes first (dry run)
{:ok, result} = GettextOps.Operations.ChangeMsgid.run("Sign In", "Log In", dry_run: true)
# => {:ok, %{files_updated: 0, entries_updated: 0, changes: [...]}}

# Specific domain
{:ok, result} = GettextOps.Operations.ChangeMsgid.run("Error", "Warning", domain: "errors")

Summary

Functions

run(old_msgid, new_msgid, opts \\ [])

Change msgid across all translation files.

update_file(file_path, old_msgid, new_msgid, dry_run \\ false)

Update msgid in a single file.

Functions

run(old_msgid, new_msgid, opts \\ [])

@spec run(String.t(), String.t(), keyword()) ::
  {:ok,
   %{
     files_updated: non_neg_integer(),
     entries_updated: non_neg_integer(),
     changes: [map()]
   }}
  | {:error, term()}

Change msgid across all translation files.

Takes an old msgid and new msgid, then updates all matching entries across all .po files and the .pot template file. Preserves all translations (msgstr).

Parameters

  • old_msgid - The current msgid to find and replace
  • new_msgid - The new msgid to use
  • opts - Keyword list of options:
    • :domain - The domain to update (default: configured default_domain)
    • :dry_run - If true, don't write files, just return what would change (default: false)

Returns

  • {:ok, result} - Success with change statistics
  • {:error, reason} - Failure with error reason

The result map contains:

  • :files_updated - Number of files actually updated (0 for dry_run)
  • :entries_updated - Total number of entries that would be/were updated
  • :changes - List of file change details

Examples

# Update msgid everywhere
{:ok, result} = GettextOps.Operations.ChangeMsgid.run("Sign In", "Log In")
# => {:ok, %{files_updated: 3, entries_updated: 3, changes: [...]}}

# Dry run to preview
{:ok, result} = GettextOps.Operations.ChangeMsgid.run("Sign In", "Log In", dry_run: true)
# => {:ok, %{files_updated: 0, entries_updated: 3, changes: [...]}}

update_file(file_path, old_msgid, new_msgid, dry_run \\ false)

@spec update_file(String.t(), String.t(), String.t(), boolean()) ::
  {:ok, non_neg_integer(), String.t()} | {:error, term()}

Update msgid in a single file.

Reads the file, finds all messages matching old_msgid, updates them to new_msgid, and writes the file back (unless dry_run is true).

Parameters

  • file_path - Path to the .po or .pot file
  • old_msgid - The msgid to find and replace
  • new_msgid - The new msgid value
  • dry_run - If true, don't write the file

Returns

  • {:ok, count, sample_msgstr} - Success with number of entries updated and a sample msgstr
  • {:error, reason} - Failure with error reason

Examples

# Update a single file
{:ok, count, msgstr} = GettextOps.Operations.ChangeMsgid.update_file(
  "priv/gettext/sv/LC_MESSAGES/default.po",
  "Sign In",
  "Log In",
  false
)
# => {:ok, 1, "Logga in"}