Fix #102: Adjust source files layout for translated content

Author: samdark

docs/architecture.md

@@ -26,7 +26,8 @@ User content lives under `content/`:
 - `config.yaml` — site-wide settings.
 - `navigation.yaml` — one or more navigation menus.
 - `<collection>/_collection.yaml` — collection settings.
-- `<collection>/*.md` — entries in a collection.
+- `<collection>/*.md` — default-language entries in a collection.
+- `<collection>/<locale>/*.md` — localized collection entries, for example `blog/ru/post.md`.
 - `authors/*.md` — author profiles.
 - `assets/` and `<collection>/assets/` — copied static files.
 

docs/configuration.md

@@ -150,9 +150,12 @@ Declare site languages in `content/config.yaml`. The first language is the defau
 languages: [en, ru]
 ```
 
-Entries are tagged with the `language` front matter field. Entries whose language
-differs from the first configured site language get their permalink prefixed automatically (e.g.,
-`/ru/blog/hello/`); default-language entries keep the plain URL (`/blog/hello/`).
+Put translations in a locale directory (`content/blog/ru/hello.md` for a collection entry
+or `content/ru/about.md` for a standalone page). The directory sets the entry language;
+the `language` front matter field remains available as an explicit override. Entries whose
+language differs from the first configured site language get their permalink prefixed
+automatically (e.g., `/ru/blog/hello/`); default-language entries keep the plain URL
+(`/blog/hello/`).
 Explicit `permalink:` overrides in front matter bypass the prefix. `languages` is required
 and must contain at least one language code.
 

docs/content.md

@@ -390,8 +390,15 @@ Translations of the same entry share the same slug but differ in language:
 
 ```
 content/blog/
-├── hello-world.md           # language: en (default)
-└── hello-world.ru.md        # language: ru
+├── hello-world.md           # default language
+├── cs/
+│   └── hello-world.md       # language: cs
+└── ru/
+    └── hello-world.md       # language: ru
 ```
 
-The language suffix in the filename (`.ru.md`) is a shorthand for setting `language: ru` in front matter.
+The directory name sets the entry language, so localized files do not need a `language`
+front matter field. An explicit `language` field takes precedence when present. Standalone
+pages use the same convention (`content/about.md`, `content/ru/about.md`). This follows
+VitePress's locale-directory layout. Locale directory names use lowercase ISO language
+codes and may include an uppercase region, for example `pt-BR`.

src/Console/BuildCommand.php

@@ -1861,13 +1861,44 @@ private function collectSourceInventory(
                     $collectionIterator = new FilesystemIterator($item->getPathname(), BaseFilesystemIterator::SKIP_DOTS);
                     foreach ($collectionIterator as $collectionItem) {
                         /** @var SplFileInfo $collectionItem */
-                        if ($collectionItem->isDir() || strtolower($collectionItem->getExtension()) !== 'md') {
+                        if ($collectionItem->isDir()) {
+                            if (preg_match('/^[a-z]{2}(?:-[A-Z]{2})?$/D', $collectionItem->getFilename()) === 1) {
+                                $languageIterator = new FilesystemIterator(
+                                    $collectionItem->getPathname(),
+                                    BaseFilesystemIterator::SKIP_DOTS,
+                                );
+                                foreach ($languageIterator as $languageItem) {
+                                    /** @var SplFileInfo $languageItem */
+                                    if (
+                                        $languageItem->isFile()
+                                        && strtolower($languageItem->getExtension()) === 'md'
+                                    ) {
+                                        $contentFiles[] = $languageItem->getPathname();
+                                    }
+                                }
+                            }
+                            continue;
+                        }
+                        if (strtolower($collectionItem->getExtension()) !== 'md') {
                             continue;
                         }
                         $contentFiles[] = $collectionItem->getPathname();
                     }
                 }
 
+                if (preg_match('/^[a-z]{2}(?:-[A-Z]{2})?$/D', $name) === 1) {
+                    $languageIterator = new FilesystemIterator(
+                        $item->getPathname(),
+                        BaseFilesystemIterator::SKIP_DOTS,
+                    );
+                    foreach ($languageIterator as $languageItem) {
+                        /** @var SplFileInfo $languageItem */
+                        if ($languageItem->isFile() && strtolower($languageItem->getExtension()) === 'md') {
+                            $contentFiles[] = $languageItem->getPathname();
+                        }
+                    }
+                }
+
                 continue;
             }
 

src/Content/Parser/ContentParser.php

@@ -129,6 +129,9 @@ public function parseStandalonePages(string $contentDir): Generator
         foreach ($iterator as $item) {
             /** @var SplFileInfo $item */
             if ($item->isDir()) {
+                if ($this->isLanguageDirectory($item)) {
+                    yield from $this->parseMarkdownFiles($item->getPathname(), '', $item->getFilename());
+                }
                 continue;
             }
 
@@ -177,6 +180,13 @@ public function parseEntries(string $contentDir, string $collectionName): Genera
         foreach ($iterator as $item) {
             /** @var SplFileInfo $item */
             if ($item->isDir()) {
+                if ($this->isLanguageDirectory($item)) {
+                    yield from $this->parseMarkdownFiles(
+                        $item->getPathname(),
+                        $collectionName,
+                        $item->getFilename(),
+                    );
+                }
                 continue;
             }
 
@@ -188,6 +198,25 @@ public function parseEntries(string $contentDir, string $collectionName): Genera
         }
     }
 
+    /**
+     * @return Generator<Entry>
+     */
+    private function parseMarkdownFiles(string $directory, string $collectionName, string $language): Generator
+    {
+        $iterator = new FilesystemIterator($directory, FilesystemIterator::SKIP_DOTS);
+        foreach ($iterator as $item) {
+            /** @var SplFileInfo $item */
+            if ($item->isFile() && $item->getExtension() === 'md') {
+                yield $this->entryParser->parse($item->getPathname(), $collectionName, $language);
+            }
+        }
+    }
+
+    private function isLanguageDirectory(SplFileInfo $item): bool
+    {
+        return preg_match('/^[a-z]{2}(?:-[A-Z]{2})?$/D', $item->getFilename()) === 1;
+    }
+
     /**
      * @return Generator<string, Author>
      */

src/Content/Parser/EntryParser.php

@@ -18,7 +18,7 @@ public function __construct(
         private array $authors = [],
     ) {}
 
-    public function parse(string $filePath, string $collectionName): Entry
+    public function parse(string $filePath, string $collectionName, string $language = ''): Entry
     {
         $result = $this->frontMatterParser->parse($filePath);
         $fields = $result['frontMatter'];
@@ -93,7 +93,7 @@ public function parse(string $filePath, string $collectionName): Entry
             layout: (string) ($fields['layout'] ?? ''),
             theme: (string) ($fields['theme'] ?? ''),
             weight: (int) ($fields['weight'] ?? 0),
-            language: (string) ($fields['language'] ?? ''),
+            language: (string) ($fields['language'] ?? $language),
             redirectTo: (string) ($fields['redirect_to'] ?? ''),
             extra: isset($fields['extra']) && is_array($fields['extra'])
                 ? $fields['extra']

tests/Unit/Console/BuildCommandTest.php

@@ -1060,7 +1060,7 @@ public function testBuildCanDisableAuthorPages(): void
         $contentDir = $this->copyContentFixture();
         file_put_contents($contentDir . '/config.yaml', "\nauthor_pages: false\n", FILE_APPEND);
 
-        $this->runBuild($contentDir);
+        $this->runBuild($contentDir, '--no-cache');
 
         assertFalse(is_dir($this->outputDir . '/authors'));
 
@@ -1498,6 +1498,38 @@ public function testI18nEntryPermalinksAreConsistentAcrossGeneratedIndexes(): vo
         assertStringContainsString('https://test.example.com/ru/blog/test-post/', $sitemap);
     }
 
+    public function testLocalizedEntryDirectorySetsLanguageAndParticipatesInIncrementalBuilds(): void
+    {
+        $contentDir = $this->copyContentFixture();
+        $config = file_get_contents($contentDir . '/config.yaml');
+        assertNotFalse($config);
+        file_put_contents(
+            $contentDir . '/config.yaml',
+            str_replace('languages: ["en"]', 'languages: ["en", "ru"]', $config),
+        );
+
+        mkdir($contentDir . '/blog/ru');
+        $entryPath = $contentDir . '/blog/ru/2024-03-15-test-post.md';
+        rename($contentDir . '/blog/2024-03-15-test-post.md', $entryPath);
+
+        $this->runBuild($contentDir);
+
+        $outputPath = $this->outputDir . '/ru/blog/test-post/index.html';
+        assertFileExists($outputPath);
+
+        $entry = file_get_contents($entryPath);
+        assertNotFalse($entry);
+        file_put_contents($entryPath, str_replace('Test Post', 'Updated Russian Post', $entry));
+
+        $result = $this->runBuildResult($contentDir);
+        $html = file_get_contents($outputPath);
+
+        assertSame(0, $result['exitCode'], $result['output']);
+        assertStringContainsString('Incremental build', $result['output']);
+        assertNotFalse($html);
+        assertStringContainsString('Updated Russian Post', $html);
+    }
+
     public function testBuildReportsInvalidEntryDateWithFilePath(): void
     {
         $contentDir = $this->createMinimalContent([

tests/Unit/Content/Parser/ContentParserTest.php

@@ -90,6 +90,67 @@ public function testParseEntries(): void
         assertCount(7, $entries);
     }
 
+    public function testParseLocalizedCollectionEntriesFromLanguageDirectories(): void
+    {
+        $dir = sys_get_temp_dir() . '/yiipress-localized-collection-' . uniqid();
+        mkdir($dir . '/blog/ru', 0o755, true);
+        file_put_contents($dir . '/blog/_collection.yaml', "title: Blog\n");
+        file_put_contents($dir . '/blog/post.md', "---\ntitle: Hello\n---\n");
+        file_put_contents($dir . '/blog/ru/post.md', "---\ntitle: Привет\n---\n");
+        file_put_contents(
+            $dir . '/blog/ru/override.md',
+            "---\ntitle: Override\nlanguage: uk\n---\n",
+        );
+
+        try {
+            $entries = iterator_to_array($this->parser->parseEntries($dir, 'blog'), false);
+            $byTitle = [];
+            foreach ($entries as $entry) {
+                $byTitle[$entry->title] = $entry;
+            }
+
+            assertCount(3, $entries);
+            assertSame('', $byTitle['Hello']->language);
+            assertSame('ru', $byTitle['Привет']->language);
+            assertSame('uk', $byTitle['Override']->language);
+            assertSame('post', $byTitle['Привет']->slug);
+        } finally {
+            unlink($dir . '/blog/ru/override.md');
+            unlink($dir . '/blog/ru/post.md');
+            unlink($dir . '/blog/post.md');
+            unlink($dir . '/blog/_collection.yaml');
+            rmdir($dir . '/blog/ru');
+            rmdir($dir . '/blog');
+            rmdir($dir);
+        }
+    }
+
+    public function testParseLocalizedStandalonePagesFromLanguageDirectories(): void
+    {
+        $dir = sys_get_temp_dir() . '/yiipress-localized-pages-' . uniqid();
+        mkdir($dir . '/cs', 0o755, true);
+        file_put_contents($dir . '/about.md', "---\ntitle: About\n---\n");
+        file_put_contents($dir . '/cs/about.md', "---\ntitle: O nás\n---\n");
+
+        try {
+            $entries = iterator_to_array($this->parser->parseStandalonePages($dir), false);
+            $byTitle = [];
+            foreach ($entries as $entry) {
+                $byTitle[$entry->title] = $entry;
+            }
+
+            assertCount(2, $entries);
+            assertSame('cs', $byTitle['O nás']->language);
+            assertSame('', $byTitle['About']->language);
+            assertSame('about', $byTitle['O nás']->slug);
+        } finally {
+            unlink($dir . '/cs/about.md');
+            unlink($dir . '/about.md');
+            rmdir($dir . '/cs');
+            rmdir($dir);
+        }
+    }
+
     public function testParseAuthors(): void
     {
         $authors = iterator_to_array($this->parser->parseAuthors($this->dataDir));