New thin layer of API extension chrome.i18n.detectLanguage

chrome/common/extensions/api/i18n.json

 // Copyright (c) 2012 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.
 
 [
   {
     "namespace": "i18n",
     "description": "Use the <code>chrome.i18n</code> infrastructure to implement internationalization across your whole app or extension.",
     "types": [],
     "functions": [
       {
         "name": "getAcceptLanguages",
         "type": "function",
         "description": "Gets the accept-languages of the browser. This is different from the locale used by the browser; to get the locale, use $(ref:i18n.getUILanguage).",
         "parameters": [
           {
             "type": "function",
             "name": "callback",
             "parameters": [
               {"name": "languages", "type": "array", "items": {"type": "string"}, "description": "Array of the accept languages of the browser, such as en-US,en,zh-CN"}

[not at google - send to devlin, 2015/07/08 19:27:30]

You may want to define a separate type for languages, even though it's a string,
it would let you centralise the documentation.

"types": {
  "id": "LanguageCode",
  "type": "string",
  "description": "..."
}

then use "$ref": "LanguageCode"

[mcindy, 2015/07/08 21:26:12]

Our 'languages' in detectLanguage is a different type from this one. This one is
an array of strings, while we use an array of object. Is it still necessary to
define it in a separate type even though we use it only once?

[not at google - send to devlin, 2015/07/08 21:47:59]

I mean purely the string. It would still be an array vs an array of objects, but
of that string.

[mcindy, 2015/07/09 18:38:27]

Done.

             ]
           }
         ]
       },
       {
         "name": "getMessage",
         "nocompile": true,
         "type": "function",
         "description": "Gets the localized string for the specified message. If the message is missing, this method returns an empty string (''). If the format of the <code>getMessage()</code> call is wrong &mdash; for example, <em>messageName</em> is not a string or the <em>substitutions</em> array has more than 9 elements &mdash; this method returns <code>undefined</code>.",
         "parameters": [
@@ skipping 17 matching lines @@
       {
         "name": "getUILanguage",
         "type": "function",
         "nocompile": true,
         "description": "Gets the browser UI language of the browser. This is different from $(ref:i18n.getAcceptLanguages) which returns the preferred user languages.",
         "parameters": [],
         "returns": {
           "type": "string",
           "description": "The browser UI language code such as en-US or fr-FR."
         }
+      },
+      {
+        "name": "detectLanguage",
+        "type": "function",
+        "description": "Detects the language of the provided text using CLD.",
+        "parameters": [
+          {
+            "type": "string",
+            "name": "text",
+            "minimum": 0,
+            "optional": true,
+            "description": "Defaults to the null string."

[not at google - send to devlin, 2015/07/08 19:27:30]

Why would we support null strings?

[mcindy, 2015/07/08 21:26:12]

The API and the CLD are implemented to handle null strings

[not at google - send to devlin, 2015/07/08 21:47:59]

What API? We're making our API right now. It doesn't make sense to try to
translate a null string, whether or not the C++ library supports it.

[mcindy, 2015/07/08 23:28:02]

Currently, when the user passes in null value, the chrome.i18n.detectLanguage
returns an error. Would it suffice to change the description of this param?

[not at google - send to devlin, 2015/07/08 23:29:07]

Just don't make it optional. Then when the extension passes in a null value, it
will throw an exception.

[mcindy, 2015/07/09 18:38:27]

Done.

+          },
+          {
+            "type": "function",
+            "name": "callback",
+            "parameters": [
+              {
+                "type": "object",
+                "name": "result",
+                "description": "LanguageDetectionResult object that holds detected langugae reliability and array of DetectedLanguage",
+                "properties": {
+                  "is_reliable": { "type": "boolean", "description": "CLD detected language reliability" },

[not at google - send to devlin, 2015/07/08 19:27:30]

APIs typically use camelcase.

[mcindy, 2015/07/08 21:26:12]

Done.

+                  "languages":
+                    {
+                      "type": "array",
+                      "description": "array of detectedLanguage",
+                      "items":
+                        {
+                          "type": "object",
+                          "description": "DetectedLanguage object that holds detected ISO language code and its percentage in the input string",
+                          "properties":
+                            {
+                              "language": { "type": "string", "description": "An ISO language code such as <code>en</code> or <code>fr</code>. For a complete list of languages supported by this method, see <a href='http://src.chromium.org/viewvc/chrome/trunk/src/third_party/cld/languages/internal/languages.cc'>kLanguageInfoTable</a>. The 2nd to 4th columns will be checked and the first non-NULL value will be returned except for Simplified Chinese for which zh-CN will be returned. For an unknown language, <code>und</code> will be returned." },

[not at google - send to devlin, 2015/07/08 19:27:30]

Why return "und" rather than null or something? What does it even mean to say
that 80% of the text is an unknown language?

[mcindy, 2015/07/08 21:26:12]

und means that the CLD cannot determine the language. So 80% of unknown means
that CLD cannot detect 80% of the input string.

[not at google - send to devlin, 2015/07/08 21:47:59]

IMO a nicer API would be to either have a null language.

[mcindy, 2015/07/08 23:12:29]

Did you mean "null" in string or null type?

[not at google - send to devlin, 2015/07/08 23:13:31]

I mean to make the language an optional field.

[mcindy, 2015/07/09 18:38:27]

Done.

+                              "percentage": { "type": "integer", "description": "The percentage of the detected language" }
+                            }
+                        }
+                    }
+                }
+              }
+            ]
+          }
+        ]
       }
     ],
     "events": []
   }
 ]