SG-12945 + SG-12581 : Added localized param to Shotgun object

docs/reference.rst

@@ -891,3 +891,45 @@ Stores the number of milliseconds to wait between request retries.  By default,
 
 In the case that both this environment variable and the config's ``rpc_attempt_interval`` property are set, the value in ``rpc_attempt_interal`` will be used.
 
+************
+Localization
+************
+
+Shotgun API offers the ability to return display namnes in user's language.
+The server currently returns localized display names for those methods:
+
+  * Shotgun.schema_entity_read
+  * Shotgun.schema_field_read
+
+Localization is disabled by default. To enable localization, set the ``localized`` property to ``True``.
+The property cannot be set at Shotgun class instantiation. When the class is instantiated, the ``localized`` config property is set to ``False``.
+
+Example for a user whose Language preference is set to Japanese:
+
+.. code-block:: python
+   :emphasize-lines: 8,19
+
+    >>> sg = Shotgun(site_name, script_name, script_key)
+    >>> sg.config.localized # checking that localization is disabled
+    False
+    >>> sg.schema_field_read('Shot')
+    {
+    'sg_vendor_groups': {
+        'mandatory': {'editable': False, 'value': False},
+        # the value field (display name) is not localized
+        'name': {'editable': True, 'value': 'Vendor Groups'},
+        ...
+    },
+    ...
+    }
+    >>> sg.config.localized = True # enabling the localization
+    >>> sg.schema_field_read('Shot')
+    {
+    'sg_vendor_groups': {
+        'mandatory': {'editable': False, 'value': False},
+        # the value field (display name) is localized
+        'name': {'editable': True, 'value': '\xe3\x83\x99\xe3\x83\xb3\xe3\x83\x80\xe3\x83\xbc \xe3\x82\xb0\xe3\x83\xab\xe3\x83\xbc\xe3\x83\x97'},
+        ...
+    },
+    ...
+    }

shotgun_api3/shotgun.py

@@ -427,6 +427,7 @@ def __init__(self, sg):
         self.session_token = None
         self.authorization = None
         self.no_ssl_validation = False
+        self.localized = False
 
     @property
     def records_per_page(self):
@@ -598,6 +599,7 @@ def __init__(self,
         self.config.convert_datetimes_to_utc = convert_datetimes_to_utc
         self.config.no_ssl_validation = NO_SSL_VALIDATION
         self.config.raw_http_proxy = http_proxy
+        self.config.localized = False
 
         try:
             self.config.rpc_attempt_interval = int(os.environ.get("SHOTGUN_API_RETRY_INTERVAL", 3000))
@@ -1818,6 +1820,9 @@ def schema_entity_read(self, project_entity=None):
             ``{'type': 'Project', 'id': 3}``
         :returns: dict of Entity Type to dict containing the display name.
         :rtype: dict
+
+        .. note::
+            The returned display names for this method will be localized when the ``localize`` Shotgun config property is set to ``True``. See :ref:`localization` for more informations.
         """
 
         params = {}
@@ -1917,6 +1922,9 @@ def schema_field_read(self, entity_type, field_name=None, project_entity=None):
         .. note::
             If you don't specify a ``project_entity``, everything is reported as visible.
 
+        .. note::
+            The returned display names for this method will be localized when the ``localize`` Shotgun config property is set to ``True``. See :ref:`localization` for more informations.
+
         >>> sg.schema_field_read('Asset', 'shots')
         {'shots': {'data_type': {'editable': False, 'value': 'multi_entity'},
                    'description': {'editable': True, 'value': ''},
@@ -3205,6 +3213,10 @@ def _call_rpc(self, method, params, include_auth_params=True, first=False):
             "content-type": "application/json; charset=utf-8",
             "connection": "keep-alive"
         }
+
+        if self.config.localized is True:
+            req_headers["locale"] = "auto"
+
         http_status, resp_headers, body = self._make_call("POST", self.config.api_path,
                                                           encoded_payload, req_headers)
         LOG.debug("Completed rpc call to %s" % (method))

tests/example_config

@@ -15,6 +15,7 @@
 
 # Full url to the Shotgun server server
 # e.g. http://my-company.shotgunstudio.com
+# be careful to not end server_url with a "/", or some tests may fail
 server_url     : http://0.0.0.0:3000
 # script name as key as listed in admin panel for your server
 script_name    : test script name

tests/test_client.py

@@ -184,6 +184,28 @@ def test_authorization(self):
         expected = "Basic " + b64encode(urllib.parse.unquote(login_password)).strip()
         self.assertEqual(expected, headers.get("Authorization"))
 
+    def test_localization_header_default(self):
+        """Localization header not passed to server without explicitly setting SG localization config to True"""
+        self.sg.info()
+
+        args, _ = self.sg._http_request.call_args
+        (_, _, _, headers) = args
+        expected_header_value = "auto"
+
+        self.assertEqual(None, headers.get("locale"))
+
+    def test_localization_header_when_localized(self):
+        """Localization header passed to server when setting SG localization config to True"""
+        self.sg.config.localized = True
+
+        self.sg.info()
+
+        args, _ = self.sg._http_request.call_args
+        (_, _, _, headers) = args
+        expected_header_value = "auto"
+
+        self.assertEqual("auto", headers.get("locale"))
+
     def test_user_agent(self):
         """User-Agent passed to server"""
         # test default user agent