add history note and api docs

HISTORY.rst

@@ -35,9 +35,14 @@
 .. :changelog:
 
 
-..
-  Unreleased Changes
-  ------------------
+
+Unreleased Changes
+------------------
+* General:
+    * Add a ``--language`` argument to the command-line interface, which will
+      translate model names, specs, and validation messages.
+    * Accept a ``language`` query parameter at the UI server endpoints, which
+      will translate model names, specs, and validation messages.
 
 3.9.2 (2021-10-29)
 ------------------

doc/api-docs/installing.rst

@@ -31,7 +31,7 @@ Replace ``<python version>`` with a python version known to be compatible with t
 Replace ``<gdal version>`` with a GDAL version known to be compatible with the desired invest version.
 Replace ``<invest version>`` with the desired invest version.
 
-Most of the time, it is not really necessary to specify the versions of ``python``, ``gdal``, and ``natcap.invest``. If you do not specify a version, the latest version will be installed. Usually the latest versions are compatible with each other, but not always. Specifying versions that are known to work can prevent some problems. You can find the supported range of GDAL versions in the [requirements.txt](https://github.com/natcap/invest/blob/main/requirements.txt) (be sure to switch to the desired release tag in the dropdown).
+Most of the time, it is not really necessary to specify the versions of ``python``, ``gdal``, and ``natcap.invest``. If you do not specify a version, the latest version will be installed. Usually the latest versions are compatible with each other, but not always. Specifying versions that are known to work can prevent some problems. You can find the supported range of GDAL versions in the `requirements.txt <https://github.com/natcap/invest/blob/main/requirements.txt>`_ (be sure to switch to the desired release tag in the dropdown).
 
 **Example for InVEST 3.9.1**::
 
@@ -54,7 +54,7 @@ Here is an explanation of what the commands are doing:
 
    ``conda create -y -c conda-forge -n <name> python=<python version>``
 
-   To be safe, you should **always install ``natcap.invest``` into a brand-new virtual environment**. This way you can be sure you have all the right versions of dependencies. Many issues with installing or using the ``natcap.invest`` package arise from dependency problems, and it's a lot easier to create a new environment than it is to fix an existing one.
+   To be safe, you should **always install** ``natcap.invest`` **into a brand-new virtual environment**. This way you can be sure you have all the right versions of dependencies. Many issues with installing or using the ``natcap.invest`` package arise from dependency problems, and it's a lot easier to create a new environment than it is to fix an existing one.
 
 2. Activate the brand-new environment just created.
 
@@ -78,7 +78,7 @@ Here is an explanation of what the commands are doing:
 
       pip install natcap.invest[ui]=<invest version>
 
-   The ``[ui]`` tells `pip` to also install all the dependencies needed for the UI.
+   The ``[ui]`` tells ``pip`` to also install all the dependencies needed for the UI.
 
 
 Python Dependencies

doc/api-docs/scripting.rst

@@ -302,6 +302,39 @@ Using the parameter study example, this might look like:
            natcap.invest.ndr.ndr.execute(args)
 
 
+====================
+Internationalization
+====================
+
+If you use the InVEST python API to access model names, `ARGS_SPEC`s, or validation messages, you can translate those strings using `gettext`:
+
+.. code-block:: python
+
+    import gettext
+    import pkg_resources
+
+    language_code = 'en'  # replace with your desired ISO 639-1 language code
+
+    # locate the internationalization data included with the invest package
+    # for languages supported by invest
+    # or alternatively, provide your own
+    locale_dir = pkg_resources.resource_filename('natcap.invest', 'internationalization/locales/')
+
+    language = gettext.translation(
+        'messages',
+        languages=[language_code],
+        localedir=locale_dir)
+    language.install()
+
+    import natcap.invest.carbon
+    ...
+
+Note that `natcap.invest` defines the `_(...)` function globally in `builtins`. When you import anything from `natcap.invest`, `_` is first defined to return the default English. This way everything works whether or not the client sets up `gettext`.
+
+See the `GNU gettext manual <https://www.gnu.org/software/gettext/manual/gettext.html>`_ and the `Python gettext documentation <https://docs.python.org/3/library/gettext.html>`_ for more information.
+
+
+
 =======
 Summary
 =======

src/natcap/invest/cli.py

@@ -248,8 +248,9 @@ def main(user_args=None):
 
     parser.add_argument(
         '-L', '--language', default='en', choices=['en', 'es'],
-        help=('The language to use. Allowed options are en (English) or es '
-              '(Spanish).'))
+        help=('Choose a language. Model specs, names, and validation messages '
+              'will be translated. Log messages are not translated. Value '
+              'should be an ISO 639-1 language code.'))
 
     subparsers = parser.add_subparsers(dest='subcommand')