|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +require 'fastlane/action' |
| 4 | +require_relative '../../helper/string_placeholders_helper' |
| 5 | +require_relative '../../helper/ios/ios_l10n_helper' |
| 6 | +require_relative '../../helper/ios/ios_strings_file_validation_helper' |
| 7 | + |
| 8 | +module Fastlane |
| 9 | + module Actions |
| 10 | + class IosLintLocalizationPlaceholderChangesAction < Action |
| 11 | + def self.run(params) |
| 12 | + # Duplicate keys must be caught *before* the comparison: `plutil` silently keeps only the last |
| 13 | + # value for a duplicated key, so a duplicate could hide a real placeholder change. They always |
| 14 | + # abort — independently of `abort_on_violations`, which only governs *placeholder changes* — |
| 15 | + # because the comparison itself is unreliable until each key is defined exactly once. |
| 16 | + if params[:check_duplicate_keys] |
| 17 | + duplicate_keys = duplicate_keys_by_file(params) |
| 18 | + unless duplicate_keys.empty? |
| 19 | + report_duplicate_keys(duplicate_keys) |
| 20 | + UI.abort_with_message!(duplicate_keys_abort_message(duplicate_keys)) |
| 21 | + end |
| 22 | + end |
| 23 | + |
| 24 | + old_strings = read_strings(params[:old_file]) |
| 25 | + new_strings = read_strings(params[:new_file]) |
| 26 | + |
| 27 | + violations = Fastlane::Helper::StringPlaceholdersHelper.incompatible_placeholder_changes(old_strings, new_strings) |
| 28 | + report(violations) |
| 29 | + |
| 30 | + UI.abort_with_message!(abort_message(violations.length)) if !violations.empty? && params[:abort_on_violations] |
| 31 | + |
| 32 | + violations |
| 33 | + end |
| 34 | + |
| 35 | + # Reads a `.strings` file into a `{ key => value }` hash. A malformed file is an *input* error |
| 36 | + # (like a missing file), so surface a clean, user-facing message naming it rather than letting a |
| 37 | + # raw `plutil` stderr dump escape the lane. `read_strings_file_as_hash` shells out to `plutil`, |
| 38 | + # which handles text/XML/binary plists, so this only trips on genuinely unparseable input. |
| 39 | + def self.read_strings(path) |
| 40 | + strings = |
| 41 | + begin |
| 42 | + Fastlane::Helper::Ios::L10nHelper.read_strings_file_as_hash(path: path) |
| 43 | + rescue StandardError => e |
| 44 | + UI.user_error!("Could not parse `#{File.basename(path)}` as a `.strings` file. #{e.message.strip}") |
| 45 | + end |
| 46 | + return strings if strings.is_a?(Hash) |
| 47 | + |
| 48 | + UI.user_error!("`#{File.basename(path)}` is not a valid `.strings` file (expected a dictionary of key/value pairs).") |
| 49 | + end |
| 50 | + |
| 51 | + def self.report(violations) |
| 52 | + if violations.empty? |
| 53 | + UI.success('No incompatible placeholder changes found between the two versions of the strings file.') |
| 54 | + return |
| 55 | + end |
| 56 | + |
| 57 | + violations.each do |violation| |
| 58 | + UI.error <<~MSG |
| 59 | + `#{violation[:key]}` changed its format placeholders incompatibly: |
| 60 | + was: #{violation[:old].inspect} [#{describe_signature(violation[:old_signature])}] |
| 61 | + now: #{violation[:new].inspect} [#{describe_signature(violation[:new_signature])}] |
| 62 | + MSG |
| 63 | + end |
| 64 | + end |
| 65 | + |
| 66 | + def self.describe_signature(signature) |
| 67 | + signature.empty? ? 'no placeholders' : signature |
| 68 | + end |
| 69 | + |
| 70 | + def self.abort_message(count) |
| 71 | + <<~MSG |
| 72 | + #{count} localization key(s) changed their format placeholders incompatibly. |
| 73 | +
|
| 74 | + Existing translations are keyed by the string's key, not its English text, so changing |
| 75 | + the placeholders of an existing key would silently break every translation for that key. |
| 76 | + Give the changed copy a brand new key instead, so the previous translations stay valid |
| 77 | + for the previous key and the new copy gets translated from scratch. |
| 78 | + MSG |
| 79 | + end |
| 80 | + |
| 81 | + # Finds duplicate keys in the old and new files, returned as `{ path => { key => [lines] } }`, |
| 82 | + # only including files that actually have duplicates. |
| 83 | + # |
| 84 | + # Only ASCII-plist (`:text`) files can be inspected: XML/binary plists can't represent a |
| 85 | + # duplicate key. A `:text` file the validator can't parse is skipped with a warning rather |
| 86 | + # than failing the whole check. |
| 87 | + def self.duplicate_keys_by_file(params) |
| 88 | + [params[:old_file], params[:new_file]].uniq.each_with_object({}) do |path, result| |
| 89 | + duplicates = duplicate_keys_in(path) |
| 90 | + result[path] = duplicates unless duplicates.empty? |
| 91 | + end |
| 92 | + end |
| 93 | + |
| 94 | + def self.duplicate_keys_in(path) |
| 95 | + return {} unless Fastlane::Helper::Ios::L10nHelper.strings_file_type(path: path) == :text |
| 96 | + |
| 97 | + Fastlane::Helper::Ios::StringsFileValidationHelper.find_duplicated_keys(file: path) |
| 98 | + rescue StandardError => e |
| 99 | + UI.important("Could not check `#{File.basename(path)}` for duplicate keys, skipping: #{e.message}") |
| 100 | + {} |
| 101 | + end |
| 102 | + |
| 103 | + def self.report_duplicate_keys(duplicate_keys) |
| 104 | + duplicate_keys.each do |path, duplicates| |
| 105 | + UI.error <<~MSG |
| 106 | + `#{File.basename(path)}` defines #{duplicates.count} key(s) more than once: |
| 107 | + #{duplicates.map { |key, lines| " `#{key}` at lines #{lines.join(', ')}" }.join("\n")} |
| 108 | + MSG |
| 109 | + end |
| 110 | + end |
| 111 | + |
| 112 | + def self.duplicate_keys_abort_message(duplicate_keys) |
| 113 | + count = duplicate_keys.values.sum(&:count) |
| 114 | + <<~MSG |
| 115 | + #{count} localization key(s) are defined more than once in the source strings. |
| 116 | +
|
| 117 | + Parsing `.strings` files relies on `plutil`, which silently keeps only the *last* value for |
| 118 | + a duplicated key. This check would therefore compare against the wrong value and could miss a |
| 119 | + real, translation-breaking placeholder change — the exact failure it exists to catch. Define |
| 120 | + each key exactly once and regenerate the file before re-running this check. |
| 121 | + MSG |
| 122 | + end |
| 123 | + |
| 124 | + ##################################################### |
| 125 | + # @!group Documentation |
| 126 | + ##################################################### |
| 127 | + |
| 128 | + def self.description |
| 129 | + 'Checks that no existing localization key changed its format placeholders between two versions of a source `.strings` file' |
| 130 | + end |
| 131 | + |
| 132 | + def self.details |
| 133 | + <<~DETAILS |
| 134 | + Compares two versions (old vs new) of the same base-language `.strings` file and reports any |
| 135 | + key — present in both — whose format placeholders (`%@`, `%1$d`, …) changed in count, position, |
| 136 | + or argument type. |
| 137 | +
|
| 138 | + This is the temporal counterpart to `ios_lint_localizations` (which compares each translation |
| 139 | + against the base language at a single point in time). Translations are filed by key, not by |
| 140 | + English text, so changing the placeholders of an existing key silently breaks every translation |
| 141 | + of that key. New and removed keys are ignored on purpose: copy that needs different placeholders |
| 142 | + is expected to land under a brand new key. |
| 143 | +
|
| 144 | + By default it also aborts if either input file defines the same key more than once: `plutil` |
| 145 | + silently keeps only the last value for a duplicated key, which would let a duplicate hide a |
| 146 | + real placeholder change. Disable this with `check_duplicate_keys: false`. |
| 147 | +
|
| 148 | + Note: parsing `.strings` files relies on `plutil`, so this action only runs on macOS. |
| 149 | + DETAILS |
| 150 | + end |
| 151 | + |
| 152 | + def self.available_options |
| 153 | + [ |
| 154 | + FastlaneCore::ConfigItem.new( |
| 155 | + key: :old_file, |
| 156 | + env_name: 'FL_IOS_LINT_L10N_PLACEHOLDER_CHANGES_OLD_FILE', |
| 157 | + description: 'Path to the previous version of the base-language `.strings` file', |
| 158 | + optional: false, |
| 159 | + type: String, |
| 160 | + verify_block: proc do |value| |
| 161 | + UI.user_error!("`old_file` not found at path: #{value}") unless File.exist?(value) |
| 162 | + end |
| 163 | + ), |
| 164 | + FastlaneCore::ConfigItem.new( |
| 165 | + key: :new_file, |
| 166 | + env_name: 'FL_IOS_LINT_L10N_PLACEHOLDER_CHANGES_NEW_FILE', |
| 167 | + description: 'Path to the newly-generated version of the base-language `.strings` file', |
| 168 | + optional: false, |
| 169 | + type: String, |
| 170 | + verify_block: proc do |value| |
| 171 | + UI.user_error!("`new_file` not found at path: #{value}") unless File.exist?(value) |
| 172 | + end |
| 173 | + ), |
| 174 | + FastlaneCore::ConfigItem.new( |
| 175 | + key: :abort_on_violations, |
| 176 | + env_name: 'FL_IOS_LINT_L10N_PLACEHOLDER_CHANGES_ABORT', |
| 177 | + description: 'Should we abort the rest of the lane with a global error if any incompatible changes are found?', |
| 178 | + optional: true, |
| 179 | + default_value: true, |
| 180 | + type: Boolean |
| 181 | + ), |
| 182 | + FastlaneCore::ConfigItem.new( |
| 183 | + key: :check_duplicate_keys, |
| 184 | + env_name: 'FL_IOS_LINT_L10N_PLACEHOLDER_CHANGES_CHECK_DUPLICATE_KEYS', |
| 185 | + description: 'Abort if either input file defines the same key more than once. `plutil` keeps only the last value for a duplicated key, which would otherwise let a duplicate silently hide a real placeholder change', |
| 186 | + optional: true, |
| 187 | + default_value: true, |
| 188 | + type: Boolean |
| 189 | + ), |
| 190 | + ] |
| 191 | + end |
| 192 | + |
| 193 | + def self.return_type |
| 194 | + :array |
| 195 | + end |
| 196 | + |
| 197 | + def self.return_value |
| 198 | + 'An array of incompatible changes, each a hash with the keys `:key`, `:old`, `:new`, `:old_signature` and `:new_signature`. Empty if there are no incompatible changes.' |
| 199 | + end |
| 200 | + |
| 201 | + def self.authors |
| 202 | + ['Automattic'] |
| 203 | + end |
| 204 | + |
| 205 | + def self.is_supported?(platform) |
| 206 | + %i[ios mac].include?(platform) |
| 207 | + end |
| 208 | + end |
| 209 | + end |
| 210 | +end |
0 commit comments