Update translation

This commit is contained in:
Tetrakern 2024-02-10 01:09:11 +01:00
parent a784bc48f5
commit ac3e098790
2 changed files with 92 additions and 146 deletions

49
FAQ.md
View File

@ -1,88 +1,87 @@
# Frequently Asked Questions
#### Q: How do I ... in WordPress?
### Q: How do I ... in WordPress?
This FAQ is about the Fictioneer theme. If you have questions about the WordPress content management system, better visit the [official support site](https://wordpress.org/support/) or search the Internet for tutorials. There are literally thousands.
#### Q: How do I set up my own site?
### Q: How do I set up my own site?
Assuming this is your first WordPress site, take a look at the [Installation](INSTALLATION.md) guide. If that proves insufficient, [search](https://www.google.com/search?q=wordpress+step+by+step+tutorial) the Internet for one of the many step-by-step tutorials or ask/hire someone. Just dont take the first cheap host or offer you come across, do your own research.
#### Q: Does the theme support multiple authors?
### Q: Does the theme support multiple authors?
Yes, you can use the theme for multiple authors. Just enable the option to "display authors on cards and posts" under **Fictioneer > General** and assign the author role as needed. Do not make everyone an administrator! Keep also in mind that huge visitor counts will require a more powerful server. The theme is intended for individuals and small collectives.
If you want to display multiple authors **per story or chapter,** you need to check the "Enable advanced meta fields" option under **Fictioneer > General > Compatibility.** This will display several extra inputs that most sites just do not need, hence they are hidden by default. Note that the co-authors field is a comma-separated list of IDs (i.e. positive numbers), not names.
#### Q: Can this be an archive for user contributed content?
### Q: Can this be an archive for user contributed content?
Technically, yes. However, this is not recommended for several reasons. The theme lacks a frontend content submission system, which means you need to grant random people access to the admin panels. While the included role manager allows you to restrict a users capabilities, WordPress was never intended for unsafe authors. You will need to watch and moderate everyone, making this only viable for smaller communities with a trustworthy team.
WordPress is also not a performant choice to run community sites, requiring too many server resources. You will need a good host or your own hardware, plus caching and technical expertise. This is going to be a headache. But some people have already done it despite all warnings.
#### Q: Can I use special characters in names and titles?
### Q: Can I use special characters in names and titles?
Probably, to an extend? The usual suspects have been tested to ensure Extended Latin is working, but you should not try to push it with zalgo text or worse. Some special characters are even actively filtered out to prevent certain attacks.
#### Q: Is this a block theme with full-site editing?
### Q: Is this a block theme with full-site editing?
No. Fictioneer was developed as standalone solution and to work out of the box, looking good and offering the best reading experience achievable. Full-site editing is the polar opposite of that goal.
#### Q: Is the theme available in other languages?
### Q: Is the theme available in other languages?
The theme is translation-ready but at the point of writing, only English is available. Feel free to [add your own translation](https://developer.wordpress.org/apis/internationalization/localization/) to the **languages** folder under the `fictioneer` text-domain or use a plugin. Be aware that there are JavaScript translations as well.
#### Q: Why is the ePUB download button not showing up?
### Q: Why is the ePUB download button not showing up?
You probably forgot to add a preface, which is required and should contain a copyright notice. Because once something is on the Internet, it will stay on the Internet. Make sure everything is in order. Also possible is that you somehow disabled the ePUB on the story or forgot to enable the feature in the settings.
#### Q: Why does the ePUB download only return an empty file?
### Q: Why does the ePUB download only return an empty file?
The ePUB converter is held together by rubber band and wishful thinking, with many points of failure. That is why the feature is marked as *experimental*. Likely causes include incompatible HTML in the content, CDNs that return exotic URLs, oversized images, not enough PHP memory or missing extensions (dom, zip), missing writing/reading permissions on the server, or caching (exclude `/download-epub`).
#### Q: What does the fingerprint icon on comments mean?
### Q: What does the fingerprint icon on comments mean?
That is just an unique hash to distinguish commenters with the same nickname and assign the comment edit script if you are authenticated. There are always malicious actors on the Internet who may pose as others to cause strife. Guest commenters do not have a fingerprint since their submissions are inherently untrustworthy, although a [gravatar](https://gravatar.com/) can serve the same purpose.
#### Q: Are there notification emails for story updates?
### Q: Are there notification emails for story updates?
There are not. Emails are highly problematic, even simple transactional emails about profile changes or new replies to your comments. They are expensive operations, unsafe, and have a good chance to be flagged as spam which can discredit your domain. You do not want to send emails in bulk unless you have a dedicated subscription service. Regardless, the theme does not offer this feature. Better rely on the mailers offered by your Ko-fi, Patreon, SubScribeStar, and so forth. They are better at this.
#### Q: Does the Patreon plugin work with the theme?
### Q: Does the Patreon plugin work with the theme?
This has not been tested but most likely not.
#### Q: Does the Jetpack plugin work with the theme?
### Q: Does the Jetpack plugin work with the theme?
Partially, depending on what features you want. Anything affecting the layout (aside from Gutenberg blocks) may cause issues and will probably fit poorly into the style without custom adjustments. The comment form is working but disables several theme features. The post subscription feature will not work for stories, chapters, and any other custom post types — only posts, which is by design. Analytics and dashboard features should be fine, though.
#### Q: What happened to Fictioneer version 1 to 4?
### Q: What happened to Fictioneer version 1 to 4?
They were never released or distributed, version 5 is the first public one.
#### Q: Why do the OAuth links return a 404 error?
### Q: Why do the OAuth links return a 404 error?
After activating the feature, you need to flush the permalinks. You can do this under **Settings > Permalinks** by just saving, you do not need to change anything.
#### Q: Can I use stories without chapters as oneshots?
### Q: Can I use stories without chapters as oneshots?
Nobody can stop you from doing that, but it is wrong. Stories do not have the same capabilities as chapters and the theme does not understand the concept. There will be no formatting options, bookmarks, text-to-speech, suggestions, comments, and so forth. SEO data and API responses may also be messed up. If you can live with that, go ahead.
#### Q: Why do chapter permalinks not include the story?
### Q: Why do chapter permalinks not include the story?
Because. And it is really difficult.
#### Q: Can I use the theme for Japanese, Korean, Chinese, and other logographic writing systems?
### Q: Can I use the theme for Japanese, Korean, Chinese, and other writing systems?
Apparently, even though this was never considered during development. WordPress is multi-lingual by default and the theme can be translated, which can be done with certain plugins too. You can change the word count script to count characters instead, with an optional multiplier for approximation. You will most likely need to add a [custom font](https://github.com/Tetrakern/fictioneer/blob/main/INSTALLATION.md#custom-fonts), though.
Resources:
**Resources:**
* Fictioneer > General > Chapters & Stories > Count characters instead of words
* Fictioneer > General > Chapters & Stories > Multiply the displayed word counts with \[\_\_\_\]
* Fictioneer > General > Chapters & Stories > Calculate reading time with \[\_\_\_\] words per minute
* Example font: [Noto Sans Japanese](https://fonts.google.com/noto/specimen/Noto+Sans+JP)
* Example font: [Noto Sans Korean](https://fonts.google.com/noto/specimen/Noto+Sans+KR)
* Example font: [Noto Sans Traditional Chinese](https://fonts.google.com/noto/specimen/Noto+Sans+TC)
* Example font: [Noto Sans Simplified Chinese](https://fonts.google.com/noto/specimen/Noto+Sans+SC)
* Example font: [Noto Sans Thai](https://fonts.google.com/noto/specimen/Noto+Sans+Thai)
* Example font: [Noto Sans Egyptian Hieroglyphs](https://fonts.google.com/noto/specimen/Noto+Sans+Egyptian+Hieroglyphs)
* [Installation guide for custom fonts](https://github.com/Tetrakern/fictioneer/blob/main/INSTALLATION.md#custom-fonts)
* [Noto Sans JP](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-jp): Noto Sans variant for Japanese.
* [Noto Sans KR](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-kr): Noto Sans variant for Korean.
* [Noto Sans TC](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-tc): Noto Sans variant for Traditional Chinese.
* [Noto Sans SC](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-sc): Noto Sans variant for Simplified Chinese.

View File

@ -1181,144 +1181,91 @@ Fictioneer loads the free version of [Font Awesome 6.4.2](https://fontawesome.co
### Custom Fonts
You can add custom fonts with a child theme, either by uploading a configuration folder to `/themes/your-child-theme/fonts/` or with a CDN like Google Fonts. The latter may cause privacy issues, depending on the legislation in your country. Delivering fonts from your server is legally safer, but can affect performance if you do not [leverage browser caching](#securing-wordpress--browser-caching) or use a cache plugin (which you should).
You can add custom fonts, either by uploading a configuration folder to `/themes/your-child-theme/fonts/` or with a CDN like Google Fonts. The latter is far more convenient, though it also violates the GDPR and is therefore not recommended except for testing. Delivering fonts from your server is legally safe, but can affect performance if you do not [leverage browser caching](#securing-wordpress--browser-caching) or use a cache plugin (which you should).
Following is an explanation of both options on the example of [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans?noto.query=noto+sans). Noto has also variants for logographic writing systems if you require that. Mind that not all fonts you find on the Internet are free to use.
Following is an explanation of both methods on the example of [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans?noto.query=noto+sans), which has also great variants for logographic writing systems if you require that. Mind that not all fonts you find on the Internet are free to use.
Purge the theme caches under **Fictioneer > Tools** after adding or removing a font. You may have to force-refresh too. Once everything is in order and refreshed, you can see the font listed under **Fictioneer > Fonts**. With that, you can assign the fonts to specific parts of the theme under **Appearance > Customize > Fonts**. More is possible with custom CSS.
#### 1A) Upload a font configuration folder
This option requires some preparation, but does not need custom code. Take a look at the [open-sans folder](https://github.com/Tetrakern/fictioneer/tree/main/fonts/open-sans); you will find several font files, one CSS file, and one JSON file.
This method requires some preparation. Take a look at the [roboto-serif](https://github.com/Tetrakern/fictioneer/tree/main/fonts/roboto-serif) default font folder; you will find several .woff2 files, one .css file, and one .json file. You can replicate that with relative ease using the [Google Fonts Webhelper](https://gwfh.mranftl.com/fonts/noto-sans) and a text editor of your choice. Search for "Noto Sans", select the charsets and styles you need (typically 300-700), then change the folder prefix to `../fonts/noto-sans/`. Copy the provided CSS into a new font.css file, download and unpack the archive, put everything into a "noto-sans" folder. You can rename the files, remove the comments, and minify the CSS if you got the patience. Just make sure everything is still correct.
The font.json file may seem a bit challenging, but is actually mostly informative. The only name-value pairs of importance right now are **skip**, **chapter**, **remove**, **key**, **name**, and **family**. You are encouraged to fill out the rest regardless, in case it becomes required in the future. Here is a pre-made one for Noto Sans:
You can easily replicate that
<details>
<summary>Explanations</summary><br>
| Key | Type | Explanation
| :--- | :---: | :---
| skip | boolean | Whether to skip the CSS bundling (if loaded by other means or a system font). Default `false`.
| remove | boolean | Whether to remove the font instead of adding it. Default `false`.
| chapter | boolean | Whether to make the font available in chapters. Default `false`.
| version | string | Version number. Default empty.
| key * | string | Unique identifier and key for the associative font array.
| name * | string | Display name.
| family * | string | CSS value for the font-family property (no extra quotes).
| alt | string | Fallback font-family value stack, e.g. "Helvetica, Arial". Default empty.
| type | string | Design type, such as "sans-serif", "serif", or "monospace". Default empty.
| styles | string[] | Available font-styles. Default empty.
| weights | integer[] | Available font-weights. Default empty.
| charsets | string[] | Supported writing systems. Default empty.
| formats | string[] | Formats of the font files, such as .woff2, .woff, .ttf, and more. Default empty.
| about | string | Description of the font for the admin page. Default empty.
| note | string | Special note about the font for the admin page. Default empty.
| preview | string | Changes the example sentence displayed on the admin page. Default empty.
| sources | object | Collection of sub-objects listing sources for the font. Default empty.
\* Required key-value pairs.
</details><br>
Go to the [Google Fonts Webhelper](https://gwfh.mranftl.com/fonts/noto-sans) to prepare the font files and styles. Select the charsets depending on your language requirements, then select the styles you need as with the **1A** approach. Before you copy the CSS (for modern browsers), you may want to customize the folder prefix. `../fonts/` assumes you place the files in `/themes/your-child-theme/fonts/`, but if you add more than one font, subfolders like `../fonts/noto-sans/` will make them easier to manage.
Once done, download the files and upload them to the theme folder you specified. Copy the CSS from the helper site to `/themes/your-child-theme/css/child-fonts.css` (for example, you can change the name as long as you do it everywhere).
You can add custom fonts with a child theme, which requires a series of not-quite-easy steps. This is less complicated with the Google Fonts CDN — however, that may be a privacy issue. Legally safe is to deliver the fonts from your server, as the theme does by default. Both options are explained here on the example of [Noto Sans](https://fonts.google.com/noto/specimen/Noto+Sans?noto.query=noto+sans), either as extra or primary/secondary font. Noto has also variants for logographic writing systems if you require that. Mind that not all fonts you find on the Internet are free to use.
#### 1A) Load from the Google Fonts CDN
Scroll down to **Styles** and select what you need, typically everything from 300 to 700 if you plan to replace the primary font. On the right, under **Use on the web**, you will find two options to import the font. Either will work, but lets go with **\[\<link\>\]** because it supports the preconnect feature.
Time to add some code to your **child themes functions.php**.
```php
/**
* Adds links to Google Fonts in the HTML <head>
*/
function child_add_google_fonts_to_head() {
echo '<link rel="preconnect" href="https://fonts.googleapis.com">'; /* Only once! */
echo '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>'; /* Only once! */
echo '<link href="https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;1,300;1,400;1,500;1,600;1,700&display=swap" rel="stylesheet">'; /* You can have multiple fonts, but better bundle them into one. */
```json
{
"skip": false,
"remove": false,
"chapter": true,
"version": "35",
"key": "noto-sans",
"name": "Noto Sans",
"family": "Noto Sans",
"alt": "",
"type": "sans-serif",
"styles": ["normal", "italic"],
"weights": [300, 400, 500, 600, 700],
"charsets": ["cyrillic", "cyrillic-ext", "devanagari", "greek", "greek-ext", "latin", "latin-ext", "vietnamese"],
"formats": ["woff2"],
"about": "Noto Sans is an unmodulated (“sans serif”) design for texts in the Latin, Cyrillic and Greek scripts, which is also suitable as the complementary choice for other script-specific Noto Sans fonts.",
"note": "",
"preview": "The quick brown fox jumps over the lazy dog.",
"sources": {
"googleFonts": {
"name": "Google Fonts",
"url": "https://fonts.google.com/noto/specimen/Noto+Sans"
},
"googleWebfontsHelper": {
"name": "Google Webfonts Helper",
"url": "https://gwfh.mranftl.com/fonts/noto-sans?subsets=cyrillic,cyrillic-ext,devanagari,greek,greek-ext,latin,latin-ext,vietnamese"
}
}
}
add_action( 'wp_head', 'child_add_google_fonts_to_head' );
```
#### 1B) Load from your server
You can find a collection of pre-made font folders under [/repo/fonts/](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts). Currently available:
Go to the [Google Fonts Webhelper](https://gwfh.mranftl.com/fonts/noto-sans) to prepare the font files and styles. Select the charsets depending on your language requirements, then select the styles you need as with the **1A** approach. Before you copy the CSS (for modern browsers), you may want to customize the folder prefix. `../fonts/` assumes you place the files in `/themes/your-child-theme/fonts/`, but if you add more than one font, subfolders like `../fonts/noto-sans/` will make them easier to manage.
* [Noto Sans](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans): The Noto Sans font from Google.
* [Noto Sans JP](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-jp): Noto Sans variant for Japanese.
* [Noto Sans KR](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-kr): Noto Sans variant for Korean.
* [Noto Sans TC](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-tc): Noto Sans variant for Traditional Chinese.
* [Noto Sans SC](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/noto-sans-sc): Noto Sans variant for Simplified Chinese.
* [Special Elite](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/special-elite): Typewriter-like font good for headings or special sections.
* [Verdana](https://github.com/Tetrakern/fictioneer/tree/main/repo/fonts/verdana): Web safe font and example for adding pre-installed device fonts.
Once done, download the files and upload them to the theme folder you specified. Copy the CSS from the helper site to `/themes/your-child-theme/css/child-fonts.css` (for example, you can change the name as long as you do it everywhere).
#### 1B) Load from the Google Fonts CDN
Time to add some code to your **child themes functions.php**.
Visit [Google Fonts](https://fonts.google.com/) and browse for a font you like. On the **Specimen** tab, scroll down to **Styles** and select what you need, typically everything from 300 to 700 if you want to cover all cases of the theme. If some styles are missing, you can still use the font — just perhaps not as primary one. On the right, under **Use on the web**, choose the **\<link\>** option and copy the link of the href attribute (nothing else). Make sure only one font is selected, because bundled font links are currently not understood by the theme.
```php
/**
* Enqueue stylesheet with font definitions
*/
function child_enqueue_fonts() {
wp_enqueue_style(
'child-fonts',
get_stylesheet_directory_uri() . '/css/child-fonts.css',
array( 'fictioneer-application' ),
'1.0.0' // The version of your child theme, used for cache busting.
);
}
add_action( 'wp_enqueue_scripts', 'child_enqueue_fonts', 99 );
/**
* Exclude stylesheets from Autoptimize (if installed)
*
* Note: Autoptimize (and maybe other CSS optimization plugins) will
* break the stylesheet, making it necessary to exclude it.
*
* @param string $exclude List of current excludes.
*
* @return string The updated exclusion string.
*/
function child_ao_exclude_fonts_css( $exclude ) {
return $exclude . ', child-fonts.css';
}
add_filter( 'autoptimize_filter_css_exclude', 'child_ao_exclude_fonts_css', 10, 1 );
```
#### 2) Apply to the fonts
With the font loaded, you need to actually apply it. The approach depends on whether you just want an extra font for the chapter formatting options or replace the site fonts (Open Sans). Only do one of them (unless you add several fonts).
Time to add even more code to your **child themes functions.php**.
```php
/**
* Add font to chapter formatting options
*
* @param array $fonts Currently registered fonts.
*
* @return array Updated fonts.
*/
function fictioneer_child_add_custom_fonts( $fonts ) {
$fonts[] = array(
'css' => 'Noto Sans', // CSS font-family value
'name' => 'Noto Sans', // Display name
'alt' => 'Open Sans' // Fallback CSS font-family value (optional)
);
/*
// Repeat this for more fonts.
$fonts[] = array(
'css' => 'Other Font',
'name' => 'Other Font',
'alt' => 'Open Sans'
);
*/
return $fonts;
}
add_filter( 'fictioneer_filter_fonts', 'fictioneer_child_add_custom_fonts' );
/* ===== OR IF YOU WANT TO REPLACE THE PRIMARY SITE FONT ===== */
define( 'FICTIONEER_PRIMARY_FONT_CSS', 'Noto Sans' ); // CSS font-family value
define( 'FICTIONEER_PRIMARY_FONT_NAME', 'Noto Sans' ); // Display name
```
Now the font is properly registered and can be used in chapters. However, if you want to replace the primary font for the whole site, you need a bit of additional CSS. You can put that into a stylesheet or in **Appearance > Customize > Additional CSS**. You can also apply fonts conditionally, as explained under [Dark/Light Mode & Media Queries](#darklight-mode--media-queries). You can find all font properties [here](https://github.com/Tetrakern/fictioneer/blob/main/src/scss/common/_properties.scss#L30), but be careful not to remove the fallback fonts.
```scss
:root {
--ff-base: 'Noto Sans', 'Open Sans', var(--ff-system); /* Default font stack */
--ff-heading: 'Noto Sans', var(--ff-base); /* Font stack used for headings */
}
https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;1,300;1,400;1,500;1,600;1,700&display=swap
```
### Constants