Bug 1668175: Document how permalink prefix works for projects with config files (#1691)

docs/user/localizing-your-projects.rst

@@ -30,7 +30,7 @@ Folder structure
 ----------------
 
 To let Pontoon discover your localizable files, you'll either need to specify
-paths in the `project config file`_ or strictly follow the file and folder
+paths in the `project configuration file`_ or strictly follow the file and folder
 structure as expected by Pontoon:
 
 #. Locale folders (including source locale) must be located at the same nesting
@@ -52,7 +52,7 @@ Incorrect pattern::
 
     locales/{locale_code}/path/to/file.{locale_code}.extension
 
-.. _project config file: https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html
+.. _project configuration file: https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html
 
 Adding a new project to Pontoon
 -------------------------------
@@ -68,14 +68,16 @@ following required fields:
 #. **Locales**: select at least one Localizable locale by clicking on it.
 #. **Repository URL**: enter your repository's SSH URL of the form
    ``git@github.com:user/repo.git``.
-#. **Download prefix**: used for manually downloading files. Select any
-   localizable file on GitHub, click ``Raw`` and replace locale code and the
-   following bits in the URL with {locale_code}.
+#. **Download prefix or path to TOML file**: a URL prefix for downloading localized files. For
+   GitHub repositories, select any localized file on GitHub, click ``Raw`` and
+   replace locale code and the following bits in the URL with ``{locale_code}``.
+   If you use one, you need to select the `project configuration file`_ instead
+   of a localized file.
 #. Click **SAVE PROJECT** at the bottom of the page.
 #. After the page reloads, click **SYNC** and wait for Pontoon to import
    strings. You can monitor the progress in the Sync log (``/sync/log/``).
 #. When the synchronization is finished, you should check the imported resources
-    and the entities. If everything went okay, you can proceed to the next step.
+   and the entities. If everything went okay, you can proceed to the next step.
 #. Go to the project's admin page and change the visibility option to make
    the project public. It's required because all new projects in Pontoon are private
    by default and aren't visible to localizers and locale managers.

pontoon/base/migrations/0011_rename_download_prefix.py

@@ -0,0 +1,23 @@
+# Generated by Django 2.2.13 on 2020-09-30 11:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("base", "0010_comment_pinned"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="repository",
+            name="permalink_prefix",
+            field=models.CharField(
+                blank=True,
+                help_text="\n        A URL prefix for downloading localized files. For GitHub repositories,\n        select any localized file on GitHub, click Raw and replace locale code\n        and the following bits in the URL with `{locale_code}`. If you use a\n        project configuration file, you need to provide the path to the raw TOML\n        file on GitHub.\n    ",
+                max_length=2000,
+                verbose_name="Download prefix or path to TOML file",
+            ),
+        ),
+    ]

pontoon/base/models.py

@@ -1754,13 +1754,15 @@ class Repository(models.Model):
 
     # TODO: We should be able to remove this once we have persistent storage
     permalink_prefix = models.CharField(
-        "Download prefix",
+        "Download prefix or path to TOML file",
         blank=True,
         max_length=2000,
         help_text="""
         A URL prefix for downloading localized files. For GitHub repositories,
         select any localized file on GitHub, click Raw and replace locale code
-        and the following bits in the URL with `{locale_code}`.
+        and the following bits in the URL with `{locale_code}`. If you use a
+        project configuration file, you need to provide the path to the raw TOML
+        file on GitHub.
     """,
     )