Specify locales in "multi locale" mode

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+- Add ability to specify locales in "multi locale" mode
+
 ## [1.2.0.beta3] - 2022-10-09
 
 - Updates to Lit and Tailwind configurations

README.md

@@ -172,10 +172,11 @@ Bridgetown is built by:
 |<a href="https://github.com/nachoal">@nachoal</a>|<a href="https://github.com/deivid-rodriguez">@deivid-rodriguez</a>|<a href="https://github.com/Eric-Guo">@Eric-Guo</a>|<a href="https://github.com/jacobherrington">@jacobherrington</a>|<a href="https://github.com/fpsvogel">@fpsvogel</a>|
 |CDMX, México|Madrid, Spain|Shanghai, China|Fayetteville, AR|Lexington, KY|
 
-|<img src="https://avatars.githubusercontent.com/vvveebs?s=256" alt="vvveebs" width="128" />|<img src="https://www.gravatar.com/avatar/00000000000000000000000000000000?d=identicon&s=128&" alt="" width="128" />|
-|:---:|:---:|
-|<a href="https://github.com/vvveebs">@vvveebs</a>|You Next?|
-|London, UK|Anywhere|
+|<img src="https://avatars.githubusercontent.com/vvveebs?s=256" alt="vvveebs" width="128" />|<img src="https://avatars.githubusercontent.com/rickychilcott?s=256" alt="rickychilcott" width="128" />|<img src="https://www.gravatar.com/avatar/00000000000000000000000000000000?d=identicon&s=128&" alt="" width="128" />|
+|:---:|:---:|:---:|
+|<a href="https://github.com/vvveebs">@vvveebs</a>|<a href="https://github.com/rickychilcott">@rickychilcott</a>|You Next?|
+|London, UK|Ohio, US|Anywhere|
+
 
 Interested in joining the Bridgetown Core Team? Send a DM to Jared in [Discord](https://discord.gg/4E6hktQGz4) and let's chat!
 

bridgetown-core/lib/bridgetown-core/collection.rb

@@ -271,6 +271,7 @@ def merge_environment_specific_metadata(data_contents)
     # Read in resource from repo path
     # @param full_path [String]
     # @param manifest [Bridgetown::Configuration::SourceManifest]
+    # @return [void]
     def read_resource(full_path, manifest: nil)
       model_relative_path = relative_model_path_for(full_path, manifest: manifest)
       model = Bridgetown::Model::Base.find(
@@ -279,14 +280,20 @@ def read_resource(full_path, manifest: nil)
       )
 
       if model_is_multi_locale?(model, model_relative_path)
-        site.config.available_locales.each do |locale|
+        # If the model specifies a locales key, use that to determine the
+        # the locale of each resource, otherwise fall back to `site.config.available_locales`
+        locales = model.locales || site.config.available_locales
+
+        locales.each do |locale|
           model.locale = locale
           add_resource_from_model model
         end
+
         return
       end
 
       add_resource_from_model model
+      nil
     end
 
     # @param model [Bridgetown::Model::Base]

bridgetown-core/test/resources/src/_pages/multi-page-with-specified-locales.multi.md

@@ -0,0 +1,10 @@
+---
+layout: localization
+title: "Multi-locale with specified locales page"
+locales:
+  - en
+---
+
+{% if site.locale == "en" %}English:{% elsif site.locale == "fr" %}French:{% endif %} {{ data.title }}
+
+{{ site.locale | t }}: {{ "test.name" | t }}

bridgetown-core/test/test_locales.rb

@@ -78,6 +78,31 @@ def reset_i18n_config
     end
   end
 
+  context "one page which is generated into multiple locales (as specified in locales key)" do
+    setup do
+      reset_i18n_config
+      @site = resources_site
+      @site.process
+      # @type [Bridgetown::Resource::Base]
+      @resources = @site.collections.pages.resources.select do |page|
+        page.relative_path.to_s == "_pages/multi-page-with-specified-locales.multi.md"
+      end
+      @english_resource = @resources.find { |page| page.data.locale == :en }
+      @french_resource = @resources.find { |page| page.data.locale == :fr }
+    end
+
+    should "have the correct permalink and locale in English" do
+      assert_equal "/multi-page/", @english_resource.relative_url
+      assert_includes @english_resource.output, 'lang="en"'
+      assert_includes @english_resource.output, "<title>Multi-locale page</title>"
+      assert_includes @english_resource.output, "<p>English: Multi-locale page</p>"
+    end
+
+    should "have not have a locale in French" do
+      assert_equal @french_resource, nil
+    end
+  end
+
   context "locales and a base_path combined" do
     setup do
       reset_i18n_config

bridgetown-website/src/_docs/internationalization.md

@@ -110,7 +110,23 @@ Create a separate resource file for each locale. You can either use the `locale`
 
 ### Multi-Locale Files
 
-Use a single resource file in "multi locale" mode and use special front mater and template syntax to include translated content. You can switch to this mode by setting `locale: multi` in your front matter or using the `.multi` extension within your file name. For example: `about.multi.md`. Then you use the `locale_overrides` front matter key to include keys which will overwrite the default keys for all locales other than the default. Here's an example:
+If the same resource should be available to multiple locales, use a single resource file in "multi locale" mode and use special front mater and template syntax to include translated content. You can switch to this mode by setting `locale: multi` in your front matter or using the `.multi` extension within your file name. For example: `about.multi.md`. This will generate resources in all of your `site.config.available_locales`.
+
+If you want to only output a limited set of locales, then use the `locales` front matter key to include only the locales that should be written.
+
+
+```yaml
+---
+title: My Title
+locale: multi
+locales:
+  - en
+  - es
+  - de
+---
+```
+
+If you want to override front matter values per-locale, then you use the `locale_overrides` front matter key to include keys which will overwrite the default keys for all locales other than the default. Here's an example:
 
 ```yaml
 ---