Reports localization

src/natcap/invest/__init__.py

@@ -43,6 +43,11 @@
 LOCALE_CODE = 'en'
 
 
+def get_locale():
+    """Get the current locale code."""
+    return LOCALE_CODE
+
+
 def set_locale(locale_code):
     """Set the `gettext` attribute of natcap.invest.
 

src/natcap/invest/carbon/reporter.py

@@ -8,7 +8,7 @@
 import pygeoprocessing
 
 from natcap.invest import __version__
-from natcap.invest import gettext
+from natcap.invest import gettext, get_locale
 from natcap.invest.reports import jinja_env, raster_utils, report_constants
 from natcap.invest.reports.raster_utils import RasterDatatype, RasterPlotConfig
 from natcap.invest.spec import ModelSpec
@@ -131,7 +131,7 @@ def report(file_registry: dict, args_dict: dict, model_spec: ModelSpec,
             raster_path=file_registry['c_storage_bas'],
             datatype=RasterDatatype.continuous,
             spec=model_spec.get_output('c_storage_bas'))]
-    
+
     intermediate_raster_config_lists = [[
         RasterPlotConfig(
             raster_path=file_registry[f'c_{pool_type}_bas'],
@@ -178,7 +178,7 @@ def report(file_registry: dict, args_dict: dict, model_spec: ModelSpec,
         input_raster_config_list)
     input_raster_caption = raster_utils.caption_raster_list(
         input_raster_config_list)
-    
+
     outputs_img_src = raster_utils.plot_and_base64_encode_rasters(
         output_raster_config_list)
     output_raster_caption = raster_utils.caption_raster_list(
@@ -214,6 +214,7 @@ def report(file_registry: dict, args_dict: dict, model_spec: ModelSpec,
 
     with open(target_html_filepath, 'w', encoding='utf-8') as target_file:
         target_file.write(TEMPLATE.render(
+            locale=get_locale(),
             report_script=model_spec.reporter,
             invest_version=__version__,
             report_filepath=target_html_filepath,
@@ -230,10 +231,10 @@ def report(file_registry: dict, args_dict: dict, model_spec: ModelSpec,
             outputs_img_src=outputs_img_src,
             outputs_caption=output_raster_caption,
             intermediate_raster_sections=intermediate_raster_sections,
-            raster_group_caption=report_constants.RASTER_GROUP_CAPTION,
+            raster_group_caption=report_constants.raster_group_caption(),
             output_raster_stats_table=output_raster_stats_table,
             input_raster_stats_table=input_raster_stats_table,
-            stats_table_note=report_constants.STATS_TABLE_NOTE,
+            stats_table_note=report_constants.stats_table_note(),
             model_spec_outputs=model_spec.outputs,
         ))
 

src/natcap/invest/cli.py

@@ -8,18 +8,14 @@
 import json
 import logging
 import multiprocessing
-import os
 import pprint
 import sys
 import textwrap
 import warnings
 
 import natcap.invest
 from natcap.invest import datastack
-from natcap.invest import set_locale
-from natcap.invest import spec
 from natcap.invest import ui_server
-from natcap.invest import utils
 from natcap.invest import models
 from pygeoprocessing.utils import GDALUseExceptions
 
@@ -463,8 +459,15 @@ def main(user_args=None):
 
             target_model = models.model_id_to_pyname[args.model]
             model_module = importlib.import_module(name=target_model)
-            LOGGER.info('Imported target %s from %s',
-                        model_module.__name__, model_module)
+
+            LOGGER.info(
+                f'Imported target {model_module.__name__} from {model_module}')
+
+            generate_report = bool(model_module.MODEL_SPEC.reporter)
+            if generate_report:
+                # Reload model module to ensure text defined in model spec is
+                # localized before it is passed to the report.
+                importlib.reload(model_module)
 
             # We're deliberately not validating here because the user
             # can just call ``invest validate <datastack>`` to validate.
@@ -479,7 +482,7 @@ def main(user_args=None):
                 generate_metadata=True,
                 save_file_registry=True,
                 check_outputs=False,
-                generate_report=bool(model_module.MODEL_SPEC.reporter))
+                generate_report=generate_report)
 
         if args.subcommand == 'serve':
             ui_server.app.run(port=args.port)

src/natcap/invest/coastal_vulnerability/reporter.py

@@ -7,7 +7,7 @@
 import pandas
 
 from natcap.invest import __version__
-from natcap.invest import gettext
+from natcap.invest import gettext, get_locale
 import natcap.invest.spec
 from natcap.invest.reports import jinja_env
 
@@ -222,9 +222,17 @@ def report(file_registry, args_dict, model_spec, target_html_filepath):
 
     na_count = exposure_geo.exposure.isna().sum()
     if na_count:
+        # There is some redundancy here to ensure the checkbox label is
+        # localized properly. Note that passing an f-string to gettext will not
+        # work; we must explicitly use .format() to populate variable values.
+        if na_count == 1:
+            null_cb_name = gettext(
+                '{na_count} point missing the exposure index. Show:')
+        else:
+            null_cb_name = gettext(
+                '{na_count} points missing the exposure index. Show:')
         null_checkbox = altair.binding_checkbox(
-            name=(f"{na_count} "
-                  f"{gettext('point(s) missing the exposure index. Show:')}"))
+            name=(null_cb_name.format(na_count=na_count)))
         show_null = altair.param(value=False, bind=null_checkbox)
         null_points_chart = base_points.add_params(
             show_null
@@ -396,6 +404,7 @@ def report(file_registry, args_dict, model_spec, target_html_filepath):
 
     with open(target_html_filepath, 'w', encoding='utf-8') as target_file:
         target_file.write(TEMPLATE.render(
+            locale=get_locale(),
             report_script=model_spec.reporter,
             invest_version=__version__,
             report_filepath=target_html_filepath,

src/natcap/invest/internationalization/README.md

@@ -6,6 +6,9 @@ None of the translations files (.pot, .po, .mo) should be manually edited by us.
 ### `messages.pot`
 Message catalog template file. This contains all the strings ("messages") that are translated, without any translations. All the PO files are derived from this.
 
+### `babel_config.ini`
+Mappings file that tells pybabel where to look when extracting messages into the message catalog. By default, pybabel will extract messages from Python source files; we need this mappings file to ensure it also extracts messages from the Jinja templates that are used for HTML reports.
+
 ### `locales/`
 Locale directory. The contents of this directory are organized in a specific structure that `gettext` expects. `locales/` contains one subdirectory for each language for which there are any translations (not including the default English). The subdirectories are named after the corresponding ISO 639-1 language code. Each language subdirectory contains a directory `LC_MESSAGES`, which then contains the message catalog files for that language.
 
@@ -22,14 +25,15 @@ No changes are immediately needed when we add, remove, or edit strings that are
 When we are ready to get a new batch of translations, here is the process. These instructions assume you have defined the two-letter locale code in an environment variable `$LL`.
 
 
-1. Run the following from the root invest directory, replacing `<LANG>` with the language code:
+1. Run the following from the root invest directory, replacing `$LL` with the language code:
 ```
 pybabel extract \
    --no-wrap \
    --project InVEST \
    --version $(python -m setuptools_scm) \
    --msgid-bugs-address natcap-software@lists.stanford.edu \
    --copyright-holder "Natural Capital Alliance" \
+   --mapping src/natcap/invest/internationalization/babel_config.ini \
    --output src/natcap/invest/internationalization/messages.pot \
    src/
 
@@ -39,7 +43,7 @@ pybabel update \
    --input-file src/natcap/invest/internationalization/messages.pot \
    --output-file src/natcap/invest/internationalization/locales/$LL/LC_MESSAGES/messages.po
 ```
-This looks through the source code for strings wrapped in the `gettext(...)` function and writes them to the message catalog template. Then it updates the message catalog for the specificed language. New strings that don't yet have a translation will have an empty `msgstr` value. Previously translated messages that are no longer needed will be commented out but remain in the file. This will save translator time if they're needed again in the future.
+This looks through the source code for strings wrapped in the `gettext(...)` function and writes them to the message catalog template. Then it updates the message catalog for the specified language. New strings that don't yet have a translation will have an empty `msgstr` value. Previously translated messages that are no longer needed will be commented out but remain in the file. This will save translator time if they're needed again in the future.
 
 2. Check that the changes look correct, then commit:
 ```
@@ -69,7 +73,9 @@ Then follow the "Process to update translations" instructions above, starting fr
 * Model titles
 * `MODEL_SPEC` `name` and `about` text
 * Validation messages
-* Strings that appear in the UI, such as button labels and tooltip text
+* Strings that appear in HTML reports, such as section headings, figure captions, and table column headers
+
+Strings that appear exclusively in the Workbench UI, such as button labels and tooltip text, are also translated, but they are handled separately. See the [Workbench README](../../../../workbench/readme.md#internationalization) for details.
 
 We are not translating:
 

src/natcap/invest/internationalization/babel_config.ini

@@ -0,0 +1,9 @@
+# Extract messages from Python source files
+
+[python: **.py]
+
+# Extract messages from Jinja HTML templates
+
+[jinja2: **/templates/**.html]
+ignore_tags = script,style
+include_attrs = alt

src/natcap/invest/ndr/reporter.py

@@ -1,4 +1,3 @@
-from natcap.invest.reports import raster_utils
 from natcap.invest.reports import report_constants
 from natcap.invest.reports import sdr_ndr_report_generator
 from natcap.invest.reports.raster_utils import RasterDatatype, RasterPlotConfig
@@ -110,7 +109,7 @@ def report(file_registry, args_dict, model_spec, target_html_filepath):
         raster_path=file_registry['stream'],
         datatype=RasterDatatype.binary_high_contrast,
         spec=model_spec.get_output('stream'))
-    stream_config.caption += report_constants.STREAM_CAPTION_APPENDIX
+    stream_config.caption += report_constants.stream_caption_appendix()
     intermediate_raster_plot_configs = [
         masked_dem_config, what_drains_config, stream_config]
 

src/natcap/invest/reports/__init__.py

@@ -7,12 +7,18 @@
 import matplotlib
 import pandas
 
+from natcap.invest import gettext
+
 jinja_env = jinja2.Environment(
     loader=jinja2.PackageLoader('natcap.invest.reports', 'templates'),
     autoescape=jinja2.select_autoescape(),
-    undefined=jinja2.StrictUndefined
+    undefined=jinja2.StrictUndefined,
+    extensions=['jinja2.ext.i18n'],
 )
 
+jinja_env.install_gettext_callables(
+    gettext=gettext, ngettext=None, newstyle=True)
+
 MATPLOTLIB_PARAMS = {
     'backend': 'agg',
     # 'legend.fontsize': 'small',

src/natcap/invest/reports/report_constants.py

@@ -1,21 +1,35 @@
 from natcap.invest import gettext
 
-STATS_TABLE_NOTE = gettext(
-    '"Valid percent" indicates the percent of pixels that are not '
-    'nodata. Comparing "valid percent" values across rasters may help '
-    'you identify cases of unexpected nodata.'
-)
-
-RASTER_GROUP_CAPTION = gettext(
-    'If a plot title includes "resampled," that raster was resampled to '
-    'a lower resolution for rendering in this report. Full resolution '
-    'rasters are available in the output workspace.'
-)
-
-STREAM_CAPTION_APPENDIX = gettext(
-    ' The stream network may look incomplete at this resolution, and '
-    'therefore it may be necessary to view the full-resolution raster '
-    'in GIS to assess its accuracy.'
-)
+# All `gettext`-wrapped strings defined in this module should be returned from
+# a function, _not_ defined on the module object itself, since text defined at
+# the module level is not localized unless/until the module is reloaded.
+# Wrapping text strings in functions avoids the need to reload the module
+# and ensures text is localized properly when it is needed.
+
+
+def stats_table_note():
+    return gettext(
+        '"Valid percent" indicates the percent of pixels that are not '
+        'nodata. Comparing "valid percent" values across rasters may help '
+        'you identify cases of unexpected nodata.'
+    )
+
+
+def raster_group_caption():
+    """Get "pre-caption" note about raster resampling."""
+    return gettext(
+        'If a plot title includes "resampled," that raster was resampled to '
+        'a lower resolution for rendering in this report. Full resolution '
+        'rasters are available in the output workspace.'
+    )
+
+
+def stream_caption_appendix():
+    return gettext(
+        ' The stream network may look incomplete at this resolution, and '
+        'therefore it may be necessary to view the full-resolution raster '
+        'in GIS to assess its accuracy.'
+    )
+
 
 TABLE_PAGINATION_THRESHOLD = 10

src/natcap/invest/reports/sdr_ndr_report_generator.py

@@ -5,7 +5,7 @@
 import time
 
 from natcap.invest import __version__
-from natcap.invest import gettext
+from natcap.invest import gettext, get_locale
 from natcap.invest.reports import (
     jinja_env, report_constants, sdr_ndr_utils, raster_utils)
 
@@ -58,8 +58,11 @@ def report(file_registry, args_dict, model_spec, target_html_filepath,
         intermediate_raster_plot_configs)
     intermediates_caption = raster_utils.caption_raster_list(
         intermediate_raster_plot_configs)
+    # Note that passing an f-string to gettext will not work;
+    # we must explicitly use .format() to populate variable values.
     intermediate_outputs_heading = gettext(
-        f'Stream Network Maps (flow algorithm: {args_dict["flow_dir_algorithm"]})')
+        'Stream Network Maps (flow algorithm: {flow_dir_algorithm})'
+        ).format(flow_dir_algorithm=args_dict["flow_dir_algorithm"].upper())
 
     (ws_vector_table, ws_vector_totals_table) = (
         sdr_ndr_utils.generate_results_table_from_vector(
@@ -81,6 +84,7 @@ def report(file_registry, args_dict, model_spec, target_html_filepath,
 
     with open(target_html_filepath, 'w', encoding='utf-8') as target_file:
         target_file.write(TEMPLATE.render(
+            locale=get_locale(),
             report_script=model_spec.reporter,
             invest_version=__version__,
             report_filepath=target_html_filepath,
@@ -97,12 +101,12 @@ def report(file_registry, args_dict, model_spec, target_html_filepath,
             intermediate_outputs_heading=intermediate_outputs_heading,
             intermediate_outputs_img_src=intermediate_img_src,
             intermediate_outputs_caption=intermediates_caption,
-            raster_group_caption=report_constants.RASTER_GROUP_CAPTION,
+            raster_group_caption=report_constants.raster_group_caption(),
             ws_vector_table=ws_vector_table,
             ws_vector_totals_table=ws_vector_totals_table,
             output_raster_stats_table=output_raster_stats_table,
             input_raster_stats_table=input_raster_stats_table,
-            stats_table_note=report_constants.STATS_TABLE_NOTE,
+            stats_table_note=report_constants.stats_table_note(),
             model_spec_outputs=model_spec.outputs,
         ))
 

src/natcap/invest/reports/templates/args-table.html

@@ -6,8 +6,8 @@
   <table>
     <thead>
       <tr>
-        <th>Name</th>
-        <th>Value</th>
+        <th>{% trans %}Name{% endtrans %}</th>
+        <th>{% trans %}Value{% endtrans %}</th>
       </tr>
     </thead>
     <tbody>

src/natcap/invest/reports/templates/base.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="{{ locale }}">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{% block page_title %}InVEST Results: {{ model_name }}{% endblock page_title %}</title>
+  <title>{% block page_title %}{% trans %}InVEST Results: {{ model_name }}{% endtrans %}{% endblock page_title %}</title>
   {% block styles %}
     {% include 'styles.html' %}
   {% endblock styles %}
@@ -16,23 +16,27 @@
     {% block content scoped %}
       <h1>{{ self.page_title() }}</h1>
       <p>{{ model_description }}</p>
+      {% trans %}
       <p>To learn more about the {{ model_name }} model, visit the
         <a
           target="_blank"
-          href="https://storage.googleapis.com/releases.naturalcapitalproject.org/invest-userguide/latest/en/{{ userguide_page }}"
+          href="https://storage.googleapis.com/releases.naturalcapitalproject.org/invest-userguide/latest/{{ locale }}/{{ userguide_page }}"
         >InVEST User Guide (opens in new browser window)</a>.
       </p>
+      {% endtrans %}
     {% endblock content %}
   </main>
   {% block footer %}
   <footer class="report-container">
     <div class="report-info">
+      {% trans %}
       <p>
         This report was generated by {{ report_script }}, InVEST version {{ invest_version }}.
       </p>
       <p>
         It was saved to {{ report_filepath }} at {{ timestamp }}.
       </p>
+      {% endtrans %}
     </div>
   </footer>
   {% endblock footer %}

src/natcap/invest/reports/templates/caption.html

@@ -30,7 +30,7 @@
       {% endfor %}
       {% if source_list %}
         <p class="sources">
-          Sources: {{ source_list | join('; ') }}
+          {% trans %}Sources:{% endtrans %} {{ source_list | join('; ') }}
         </p>
       {% endif %}
     {% endif %}