localizations_validator.dart 7.96 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:convert' show json;
6 7
import 'dart:io';

8 9
import 'localizations_utils.dart';

10 11 12
// The first suffix in kPluralSuffixes must be "Other". "Other" is special
// because it's the only one that is required.
const List<String> kPluralSuffixes = <String>['Other', 'Zero', 'One', 'Two', 'Few', 'Many'];
13
final RegExp kPluralRegexp = RegExp(r'(\w*)(' + kPluralSuffixes.skip(1).join(r'|') + r')$');
14 15 16 17 18 19 20 21

class ValidationError implements Exception {
  ValidationError(this. message);
  final String message;
  @override
  String toString() => message;
}

22
/// Sanity checking of the @foo metadata in the English translations, *_en.arb.
23
///
24
/// - For each foo, resource, there must be a corresponding @foo.
25 26 27 28 29
/// - For each @foo resource, there must be a corresponding foo, except
///   for plurals, for which there must be a fooOther.
/// - Each @foo resource must have a Map value with a String valued
///   description entry.
///
30 31
/// Throws an exception upon failure.
void validateEnglishLocalizations(File file) {
32
  final StringBuffer errorMessages = StringBuffer();
33 34 35

  if (!file.existsSync()) {
    errorMessages.writeln('English localizations do not exist: $file');
36
    throw ValidationError(errorMessages.toString());
37 38
  }

39
  final Map<String, dynamic> bundle = json.decode(file.readAsStringSync()) as Map<String, dynamic>;
40

41
  for (final String resourceId in bundle.keys) {
42 43 44 45 46 47 48 49 50 51
    if (resourceId.startsWith('@'))
      continue;

    if (bundle['@$resourceId'] != null)
      continue;

    bool checkPluralResource(String suffix) {
      final int suffixIndex = resourceId.indexOf(suffix);
      return suffixIndex != -1 && bundle['@${resourceId.substring(0, suffixIndex)}'] != null;
    }
52
    if (kPluralSuffixes.any(checkPluralResource))
53 54 55 56 57
      continue;

    errorMessages.writeln('A value was not specified for @$resourceId');
  }

58
  for (final String atResourceId in bundle.keys) {
59 60 61 62
    if (!atResourceId.startsWith('@'))
      continue;

    final dynamic atResourceValue = bundle[atResourceId];
63
    final Map<String, dynamic>? atResource =
64
        atResourceValue is Map<String, dynamic> ? atResourceValue : null;
65 66 67 68 69
    if (atResource == null) {
      errorMessages.writeln('A map value was not specified for $atResourceId');
      continue;
    }

70
    final bool optional = atResource.containsKey('optional');
71
    final String? description = atResource['description'] as String?;
72
    if (description == null && !optional)
73 74
      errorMessages.writeln('No description specified for $atResourceId');

75
    final String? plural = atResource['plural'] as String?;
76 77 78 79 80 81
    final String resourceId = atResourceId.substring(1);
    if (plural != null) {
      final String resourceIdOther = '${resourceId}Other';
      if (!bundle.containsKey(resourceIdOther))
        errorMessages.writeln('Default plural resource $resourceIdOther undefined');
    } else {
82
      if (!optional && !bundle.containsKey(resourceId))
83 84 85 86
        errorMessages.writeln('No matching $resourceId defined for $atResourceId');
    }
  }

87
  if (errorMessages.isNotEmpty)
88
    throw ValidationError(errorMessages.toString());
89 90
}

91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125
/// This removes undefined localizations (localizations that aren't present in
/// the canonical locale anymore) by:
///
/// 1. Looking up the canonical (English, in this case) localizations.
/// 2. For each locale, getting the resources.
/// 3. Determining the set of keys that aren't plural variations (we're only
///    interested in the base terms being translated and not their variants)
/// 4. Determining the set of invalid keys; that is those that are (non-plural)
///    keys in the resources for this locale, but which _aren't_ keys in the
///    canonical list.
/// 5. Removes the invalid mappings from this resource's locale.
void removeUndefinedLocalizations(
  Map<LocaleInfo, Map<String, String>> localeToResources,
) {
  final Map<String, String> canonicalLocalizations = localeToResources[LocaleInfo.fromString('en')]!;
  final Set<String> canonicalKeys = Set<String>.from(canonicalLocalizations.keys);

  localeToResources.forEach((LocaleInfo locale, Map<String, String> resources) {
    bool isPluralVariation(String key) {
      final Match? pluralMatch = kPluralRegexp.firstMatch(key);
      if (pluralMatch == null)
        return false;
      final String? prefix = pluralMatch[1];
      return resources.containsKey('${prefix}Other');
    }

    final Set<String> keys = Set<String>.from(
        resources.keys.where((String key) => !isPluralVariation(key))
    );

    final Set<String> invalidKeys = keys.difference(canonicalKeys);
    resources.removeWhere((String key, String value) => invalidKeys.contains(key));
  });
}

126
/// Enforces the following invariants in our localizations:
127
///
128 129
/// - Resource keys are valid, i.e. they appear in the canonical list.
/// - Resource keys are complete for language-level locales, e.g. "es", "he".
130
///
131 132
/// Uses "en" localizations as the canonical source of locale keys that other
/// locales are compared against.
133
///
134 135
/// If validation fails, throws an exception.
void validateLocalizations(
136
  Map<LocaleInfo, Map<String, String>> localeToResources,
137 138 139
  Map<LocaleInfo, Map<String, dynamic>> localeToAttributes, {
  bool removeUndefined = false,
}) {
140
  final Map<String, String> canonicalLocalizations = localeToResources[LocaleInfo.fromString('en')]!;
141 142
  final Set<String> canonicalKeys = Set<String>.from(canonicalLocalizations.keys);
  final StringBuffer errorMessages = StringBuffer();
143
  bool explainMissingKeys = false;
144
  for (final LocaleInfo locale in localeToResources.keys) {
145
    final Map<String, String> resources = localeToResources[locale]!;
146 147 148 149 150 151 152

    // Whether `key` corresponds to one of the plural variations of a key with
    // the same prefix and suffix "Other".
    //
    // Many languages require only a subset of these variations, so we do not
    // require them so long as the "Other" variation exists.
    bool isPluralVariation(String key) {
153
      final Match? pluralMatch = kPluralRegexp.firstMatch(key);
154 155
      if (pluralMatch == null)
        return false;
156
      final String? prefix = pluralMatch[1];
157 158 159
      return resources.containsKey('${prefix}Other');
    }

160
    final Set<String> keys = Set<String>.from(
161 162 163 164 165 166
      resources.keys.where((String key) => !isPluralVariation(key))
    );

    // Make sure keys are valid (i.e. they also exist in the canonical
    // localizations)
    final Set<String> invalidKeys = keys.difference(canonicalKeys);
167
    if (invalidKeys.isNotEmpty && !removeUndefined) {
168
      errorMessages.writeln('Locale "$locale" contains invalid resource keys: ${invalidKeys.join(', ')}');
169 170
    }

171 172
    // For language-level locales only, check that they have a complete list of
    // keys, or opted out of using certain ones.
173
    if (locale.length == 1) {
174 175
      final Map<String, dynamic>? attributes = localeToAttributes[locale];
      final List<String?> missingKeys = <String?>[];
176
       for (final String missingKey in canonicalKeys.difference(keys)) {
177
        final dynamic attribute = attributes?[missingKey];
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
        final bool intentionallyOmitted = attribute is Map && attribute.containsKey('notUsed');
        if (!intentionallyOmitted && !isPluralVariation(missingKey))
          missingKeys.add(missingKey);
      }
      if (missingKeys.isNotEmpty) {
        explainMissingKeys = true;
        errorMessages.writeln('Locale "$locale" is missing the following resource keys: ${missingKeys.join(', ')}');
      }
    }
  }

  if (errorMessages.isNotEmpty) {
    if (explainMissingKeys) {
        errorMessages
          ..writeln()
          ..writeln(
            'If a resource key is intentionally omitted, add an attribute corresponding '
            'to the key name with a "notUsed" property explaining why. Example:'
          )
          ..writeln()
          ..writeln('"@anteMeridiemAbbreviation": {')
          ..writeln('  "notUsed": "Sindhi time format does not use a.m. indicator"')
          ..writeln('}');
    }
202
    throw ValidationError(errorMessages.toString());
203 204
  }
}