languagesPrivate IDL draft

chrome/common/extensions/api/language_settings_private.idl

Index: chrome/common/extensions/api/language_settings_private.idl
diff --git a/chrome/common/extensions/api/language_settings_private.idl b/chrome/common/extensions/api/language_settings_private.idl
new file mode 100644
index 0000000000000000000000000000000000000000..dd5aff9181334f03eae7a61e47b167c03c52ab63
--- /dev/null
+++ b/chrome/common/extensions/api/language_settings_private.idl
@@ -0,0 +1,118 @@
+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Use the <code>chrome.languageSettingsPrivate</code> API to get or change
+// language and input method settings.
+namespace languageSettingsPrivate {
+  // Status of a spell check dictionary download.
+  enum DownloadStatus { DOWNLOADED, DOWNLOADING, FAILURE };
+
+  dictionary Language {
+    // The unique code identifying the language.
+    DOMString code;
+    // The name of the language, in the current UI language.
+    DOMString displayName;
+    // The name of the language as it is in its own language.
+    DOMString nativeDisplayName;
+    // Whether the directionality is RTL. Defaults to false.
+    boolean? rtl;
+    // Whether the UI can be displayed in this language. Defaults to false.
+    boolean? supportsUI;
+    // Whether this language can be used for spell checking. Defaults to false.
+    boolean? supportsSpellCheck;
+    // Whether this language has translations for the current target language.
+    // Defaults to false.
+    boolean? supportsTranslate;
+  };
+
+  dictionary SpellCheckDictionaryStatus {
+    // The language code of the dictionary that the status describes.
+    DOMString languageCode;
+
+    // The downloading status.

[stevenjb, 2015/05/11 01:25:57]

nit: The download status of the dictionary.

[michaelpg, 2015/07/07 00:12:30]

Done.

+    DownloadStatus status;
+  };
+
+  dictionary InputMethod {
+    // The ID of the input method descriptor.
+    DOMString id;
+
+    // The human-readable name of the input method.
+    DOMString displayName;
+
+    // The language codes this input method supports.
+    DOMString[] languageCodes;
+
+    // True if the input method is enabled.
+    boolean enabled;
+  };
+
+  dictionary InputMethodLists {
+    // The list of built-in input methods.
+    InputMethod[] inputMethods;
+
+    // The list of component extension input methods.
+    InputMethod[] componentExtensionIMEs;
+
+    // The list of third-party extension input methods.
+    InputMethod[] thirdPartyExtensionIMEs;
+  };
+
+  callback GetLanguageListCallback = void (Language[] languages);
+  callback GetInputMethodListsCallback = void (InputMethodLists lists);
+  callback GetSpellCheckWordsCallback = void (DOMString[] words);
+  callback GetTranslateTargetLanguageCallback = void (DOMString languageCode);
+  callback GetSpellCheckDictionaryStatusCallback =
+      void (SpellCheckDictionaryStatus status);
+  callback InputMethodAddedRemovedCallback = void (DOMString inputMethodId);
+
+  interface Functions {
+    // Gets languages available for translate, spell checking, input and locale.
+    static void getLanguageList(GetLanguageListCallback callback);
+
+    // Changes the prospective locale. Takes effect after restarting Chrome.
+    static void setUILanguage(DOMString languageCode);

[stevenjb, 2015/05/11 01:25:57]

Question: How does the UI know what the current language is, and what the set
language is?

[michaelpg, 2015/05/11 08:16:01]

navigator.language provides the actual current UI language.

The currently set language (which may be the current UI language, or if not,
takes effect on signout/relaunch) is stored in Local State as intl.app_locale.
On Chrome OS only, it's also stored per user in Preferences.

I'll see how PrefService::FindPreference treats this, but if it finds the
appropriate preference store then we can just use settingsPrivate to get/set the
value.

[stevenjb, 2015/06/01 18:08:06]

As long as we document that there, I am fine with it, but it might be helpful to
provide an accessor here too so that it is crystal clear what "UILanguage"
refers to.

[michaelpg, 2015/07/07 00:12:30]

Removed from here.

+
+    // Sets the accepted languages.

[stevenjb, 2015/05/11 01:25:57]

Maybe elaborate? It's not obvious (to me) what 'accepted' means here.

[michaelpg, 2015/07/07 00:12:29]

Done. (tl;dr: a lot of things)

+    static void setLanguageList(DOMString[] languageCodes);
+
+    // Gets the current status of the spell check dictionary.
+    static void getSpellCheckDictionaryStatus(
+        GetSpellCheckDictionaryStatusCallback callback);
+
+    // Attempts to download the spell check dictionary after a failure.

[stevenjb, 2015/05/11 01:25:57]

Why do we need to expose this to the UI?

[michaelpg, 2015/05/11 08:16:01]

Options currently shows a "Retry" button if the download fails.

The mocks for MD-Settings don't use the dictionary status at all. I'll check w/
Tom & Cody. Are you suggesting the download retry should be handled
automatically?

[stevenjb, 2015/06/01 18:08:06]

Yes. IMHO, 'Retry' represents poor/lazy UI. DownloadStatus.Failure should
indicate that the dictionary is not loadable. The 'model' (i.e. Chrome) should
automatically retry if/when appropriate. (If implementing that is challenging,
we can make that a TODO, but we should omit any Retry UI and use something like
getLanguageList() to trigger a retry so that a Settings page refresh triggers
the retry).

[michaelpg, 2015/07/07 00:12:29]

Acknowledged.

+    static void retrySpellCheckDictionaryDownload();
+
+    // Gets the custom spell check words.
+    static void getSpellCheckWords(GetSpellCheckWordsCallback callback);
+
+    // Gets all supported input methods, including IMEs.
+    static void getInputMethodLists(GetInputMethodListsCallback callback);
+
+    // Enables the input method for the current user.
+    static void addInputMethod(DOMString inputMethodId);
+
+    // Disables the input method for the current user.

[stevenjb, 2015/05/11 01:25:57]

Disable (implies it remains in the list but not enabled) or Remove (implies it
will no longer be in the list)?

[michaelpg, 2015/05/11 08:16:02]

Both? The input method will be removed from the user's list of enabled input
methods. I think these method names are more precise but the comments aren't
wrong. Open to suggestions for clearer documentation.

[stevenjb, 2015/06/01 18:08:06]

"Removes the input method from the list of enabled methods, disabling the input
method for the current user." ?

[michaelpg, 2015/07/07 00:12:30]

Done.

+    static void removeInputMethod(DOMString inputMethodId);
+
+    // Gets the translate target language (in most cases, the display locale).
+    static void getTranslateTargetLangage(
+        GetTranslateTargetLanguageCallback callback);
+  };
+
+  interface Events {
+    // Called when the language used for spell checking changes or the
+    // dictionary download status changes.
+    static void onSpellCheckDictionaryChanged(
+        GetSpellCheckDictionaryStatusCallback callback);
+
+    // Called when an input method is enabled.
+    static void onInputMethodEnabled(
+        InputMethodEnabledDisabledCallback callback);
+
+    // Called when an input method is disabled.
+    static void onInputMethodDisabled(
+        InputMethodEnabledDisabledCallback callback);
+  };
+};