Skip to content

Commit

Permalink
Fix typos in localization and access-control docs (#649)
Browse files Browse the repository at this point in the history
* Fix typos in localization doc

* Fix typos in access-control doc
  • Loading branch information
ldko authored Jun 12, 2021
1 parent 12fcc87 commit 9587954
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 15 deletions.
18 changes: 10 additions & 8 deletions docs/manual/access-control.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ The embargo system allows restricting access to all URLs within a collection bas
Access to these resources is 'embargoed' until the date range is adjusted or the time interval passes.

The embargo can be used to disallow access to captures based on following criteria:

- Captures before an exact date
- Captures after an exact date
- Captures newer than a time interval
Expand Down Expand Up @@ -82,7 +83,7 @@ Access Control Files (.aclj)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

URL-based access controls are set in one or more access control JSON files (.aclj), sorted in reverse alphabetical order.
To determine the best match, a binary search is used (similar to CDXJ) lookup and then the best match is found forward.
To determine the best match, a binary search is used (similar to CDXJ lookup) and then the best match is found forward.

An .aclj file may look as follows::

Expand All @@ -96,9 +97,10 @@ Each JSON entry contains an ``access`` field and the original ``url`` field that

The JSON entry may also contain a ``user`` field, as explained below.

The prefix consists of a SURT key and a ``-`` (currently reserved for a timestamp/date range field to be added later)
The prefix consists of a SURT key and a ``-`` (currently reserved for a timestamp/date range field to be added later).

Given these rules, a user would:

* be allowed to visit ``http://httpbin.org/anything/something`` (allow)
* but would receive an 'access blocked' error message when viewing ``http://httpbin.org/`` (block)
* would receive a 404 not found error when viewing ``http://httpbin.org/anything`` (exclude)
Expand All @@ -110,7 +112,7 @@ Access Types: allow, block, exclude, allow_ignore_embargo
The available access types are as follows:

- ``exclude`` - when matched, results are excluded from the index, as if they do not exist. User will receive a 404.
- ``block`` - when matched, results are not excluded from the index, marked with ``access: block``, but access to the actual is blocked. User will see a 451
- ``block`` - when matched, results are not excluded from the index, but access to the actual content is blocked. User will see a 451.
- ``allow`` - full access to the index and the resource, but may be overriden by embargo
- ``allow_ignore_embargo`` - full access to the index and resource, overriding any embargo settings

Expand All @@ -130,9 +132,9 @@ User-Based Access Controls
The access control rules can further be customized be specifying different permissions for different 'users'. Since pywb does not have a user system,
a special header, ``X-Pywb-ACL-User`` can be used to indicate a specific user.

This setting is designed to allow a more priveleged user to access additional setting or override an embargo.
This setting is designed to allow a more privileged user to access additional content or override an embargo.

For example, the following access control settings restricts access to ``https://example.com/restricted/`` by default, but allows access for the ``staff`` user::
For example, the following access control settings restrict access to ``https://example.com/restricted/`` by default, but allow access for the ``staff`` user::

com,example)/restricted - {"access": "allow", "user": "staff"}
com,example)/restricted - {"access": "block"}
Expand All @@ -157,7 +159,7 @@ See the :ref:`config-acl-header` section in Usage for examples on how to configu
Access Error Messages
^^^^^^^^^^^^^^^^^^^^^

The special error code 451 is used to indicate that a resource has been blocked (access setting ``block``)
The special error code 451 is used to indicate that a resource has been blocked (access setting ``block``).

The `error.html <https://github.com/webrecorder/pywb/blob/master/pywb/templates/error.html>`_ template contains a special message for this access and can be customized further.

Expand Down Expand Up @@ -219,7 +221,7 @@ Access Controls for Custom Collections

For manually configured collections, there are additional options for configuring access controls.
The access control files can be specified explicitly using the ``acl_paths`` key and allow specifying multiple ACL files,
and allowing sharing access control files between different collections.
and allow sharing access control files between different collections.

Single ACLJ::

Expand Down Expand Up @@ -249,7 +251,7 @@ When finding the best rule from multiple ``.aclj`` files, each file is binary se
set merge-sorted to find the best match (very similar to the CDXJ index lookup).

Note: It might make sense to separate ``allows.aclj`` and ``blocks.aclj`` into individual files for organizational reasons,
but there is no specific need to keep more than one access control files.
but there is no specific need to keep more than one access control file.

Finally, ACLJ and embargo settings combined for the same collection might look as follows::

Expand Down
14 changes: 7 additions & 7 deletions docs/manual/localization.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ pywb can extract all text from templates and generate CSV files for translation

Locales to use are configured in the ``config.yaml``.

The command-line ``wb-manager`` utility provides a way to manages locales for translation, including generatin extracted text, update translated text.
The command-line ``wb-manager`` utility provides a way to manage locales for translation, including generating extracted text, and to update translated text.

Adding a Locale and Extracting Text
===================================
Expand All @@ -24,7 +24,7 @@ The ``<loc>`` can be one or more supported two-letter locales or CLDR language c

Localization data is placed in the ``i18n`` directory, and translatable strings can be found in ``i18n/translations/<locale>/LC_MESSAGES/messages.csv``

Each CSV file looks as follows, listing source string and an empty string for the translated version::
Each CSV file looks as follows, listing each source string and an empty string for the translated version::

"location","source","target"
"pywb/templates/banner.html:6","Live on",""
Expand All @@ -37,7 +37,7 @@ Each CSV file looks as follows, listing source string and an empty string for th

This CSV can then be passed to translators to translate the text.

(The extraction parameters arae configured to load data from ``pywb/templates/*.html`` in ``babel.ini``)
(The extraction parameters are configured to load data from ``pywb/templates/*.html`` in ``babel.ini``)


For example, the following will generate translation strings for ``es`` and ``pt`` locales::
Expand All @@ -48,9 +48,9 @@ For example, the following will generate translation strings for ``es`` and ``pt
The translatable text can then be found in ``i18n/translations/es/LC_MESSAGES/messages.csv`` and ``i18n/translations/pt/LC_MESSAGES/messages.csv``.


The CSV files should be updated with a translation for each string in the target column.
The CSV files should be updated with a translation for each string in the ``target`` column.

The extract commannd add any new strings without overwriting existing translations, so it is safe to run multiple times.
The extract command adds any new strings without overwriting existing translations, so after running the update command to compile translated strings (described below), it is safe to run the extract command again.


Updating Locale Catalog
Expand All @@ -66,7 +66,7 @@ This will parse the CSVs and compile the translated string tables for use with p
Specifying locales in pywb
==========================

To enable the locales in pywb, add one or more locales can be added to the ``locales`` key in ``config.yaml``, ex::
To enable the locales in pywb, one or more locales can be added to the ``locales`` key in ``config.yaml``, ex::

locales:
- en
Expand Down Expand Up @@ -120,7 +120,7 @@ Listing and Removing Locales

To list the locales that have previously been added, you can also run ``wb-manager i18n list``.

To disable a locale from being used in pywb, simply remove it from the ``locales`` key in ``config.yaml``
To disable a locale from being used in pywb, simply remove it from the ``locales`` key in ``config.yaml``.

To remove data for a locale permanently, you can run: ``wb-manager i18n remove <loc>``. This will remove the locale directory on disk.

Expand Down

0 comments on commit 9587954

Please sign in to comment.