Update component documentation for docs list

app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -262,3 +262,21 @@ examples:
         - link:
             text: 'Criteria'
             description: 'no url provided, just text'
+  with_locale_specified:
+    description: |
+      The component is used on translated pages that don’t have a translation for the document link text or the metadata. This means that it could display the fallback English string if the translate method can’t find an appropriate translation. This makes sure that the lang can be set to ensure that browsers understand which parts of the page are in each language.
+
+      Locales can be set separately for the document link text and individual metadata items. To set link text locale, pass a locale attribute along with the link object. To set metadata locale, pass a locale attribute containing a parallel object to your metadata (depending on which metadata have translations and which need a lang attribute to specify that they are in a different language).
+
+      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.
+    data:
+      items:
+      - link:
+          text: 'Tryloywder Uwch Staff Ysgrifennydd Gwladol Cymru Ionawr-Mawrth 2020'
+          path: '/government/publications/office-of-the-secretary-of-state-for-wales-senior-staff-transparency-january-march-2020'
+          locale: 'cy'
+        metadata:
+          public_updated_at: 2016-06-27 10:29:44
+          document_type: 'Data tryloywder'
+          locale:
+            document_type: 'cy'