VSinerva/freesewing
1
0
Fork 0
Code Activity

chore(markdown): Updated dev docs for strapi/crowdin changes

Browse source
This commit is contained in:
Joost De Cock 2021-08-26 11:51:47 +02:00
parent 7779bb4659
commit b8352abef3
26 changed files with 126 additions and 518 deletions
Download patch file Download diff file Expand all files Collapse all files

19
markdown/dev/editors/content/dev/en.md
View file

@ -1,19 +0,0 @@
---
title: freesewing.dev
order: 20
---
The content for our freesewing.dev website is stored in the `dev` folder
of [our Markdown repository](https://github.com/freesewing/markdown/).
Each page is in its own folder and contains an `en.md` file.
All images and other media used by the page/post will also be contained in the folder.
<Note>
You might still see some files from other langauges (like `es.md`, `fr.md`, `de.md`, or `nl.md`) that
predate the decision to only provide freesewing.dev in English.
You can remove those files.
</Note>

16
markdown/dev/editors/content/emails/en.md
View file

@ -1,16 +0,0 @@
---
title: Emails
order: 50
---
By *emails* we mean the kind of automated emails that are sent out by
the FreeSewing backend. Like when you sign up, or ask for a password reset
and so on.
The content of these emails comes from the `src/templates` folder
of [our backend repository](https://github.com/freesewing/backend).
However, most of the actual text that the user gets to see is defined in one of
the YAML files of our i18n package (specifically `email.yaml).
See [strings](/editors/content/strings/) for more details.

44
markdown/dev/editors/content/en.md
View file

@ -4,6 +4,46 @@ title: Content sources
As an editor, you need to know where you can find/edit what type of content.
Below is a list of all our content sources:
## The freesewing monorepo
<ReadMore list />
Our [freesewing monorepo](https://github/freesewing/freesewing) holds the majority of all our code and content.
Here you can find:
- Content for freesewing.org: in the `markdown/org` folder
- Content for freesewing.dev: in the `markdown/dev` folder
- Strings used throughout the software: in the `packages/i18n/src/locales` folder
<Note>
##### Edit, don't translate
As an editor, you only ever work with the `en.md` files. The rest is for the translators.
When creating new content, you don't have to create the other files, only `en.md`.
The rest will be created automatically.
</Note>
## Strapi
FreeSewing uses [the Strapi content management system](https://strapi.io/) as a headless content management system for various posts:
- For blog posts on freesewing.org
- For showcase posts on freesewing.org
- For blog posts on freesewing.dev
- For newsletter editions
The Strapi instance is available at [posts.freesewing.org](https://posts.freesewing.org)
## Emails sent from our backend
The last bit of content is emails that are sent out from our backend systems.
They are in the [backend repository](https://github.com/freesewing/backend).
<Note>
It's on our todo list to bring the backend code into our monorepo
</Note>

6
markdown/dev/editors/content/newsletter/en.md
View file

@ -1,6 +0,0 @@
---
title: Newsletter
order: 40
---
<Fixme>Under construction</Fixme>

35
markdown/dev/editors/content/org/en.md
View file

@ -1,35 +0,0 @@
---
title: freesewing.org
order: 10
---
The content for our freesewing.org website is stored in the `org` folder
of [our Markdown repository](https://github.com/freesewing/markdown/).
Within it, you will find the following 4 subfolders:
- `org/blog`: Holds the freesewing.org blog posts
- `org/docs`: Holds the freesewing.org documentation (everything under `/docs` on the site)
- `org/showcase`: Holds the freesewing.org showcase posts
- `org/ui`: Holds snippets of text used throughout the UI that are too large or volatile to be translated as strings
Each page or post is in its own folder that contains the following five files:
- `de.md`: The German version
- `en.md`: The (original) English version
- `es.md`: The Spanish version
- `fr.md`: The French version
- `nl.md`: The Dutch version
All images and other media used by the page/post will also be contained in the folder.
<Note>
##### Edit, don't translate
As an editor, you only ever work with the `en.md` files. The rest is for the translators.
When creating new content, you don't have to create the other files, only `en.md`.
The rest will be created automatically.
</Note>

32
markdown/dev/editors/content/strings/en.md
View file

@ -1,32 +0,0 @@
---
title: Strings
order: 30
---
With *strings* we mean all of the translation stored in [our i18n package](/reference/pacakges/i18n) that
provides internationalization.
They are a number of YAML files that you can find in the `packages/i18n/src/locales/en` folder of
[our monorepo](https://github.com/freesewing/freesewing/)
These files are typically the domain of translators, as they contain short strings and snippets of
text used throughout the software/website rather than flowing text.
However, as an editor, it's good to know where they live.
<Note>
##### Beware that making changes will have ripple-effects on translation
If you make a change to one of the (English) YAML files, this will have a knock-on
effect on translators as this string now needs to be re-translated.
</Note>
<Warning>
Never make changes in the non-English files as they will simply be
overwritten by our translation software.
</Warning>

13
markdown/dev/editors/howtos/blogpost/add-body/en.md
View file

@ -1,13 +0,0 @@
---
title: Add the body of the blog post
order: 90
---
Below the frontmatter, you can write the body of your blog post, [using markdown](/editors/markdown/).
<Tip>
You can look at [one of the many blog posts](https://github.com/freesewing/markdown/tree/develop/org/blog) for examples.
</Tip>

34
markdown/dev/editors/howtos/blogpost/add-frontmatter/en.md
View file

@ -1,34 +0,0 @@
---
title: Add the frontmatter
order: 40
---
Frontmatter is metadata that we add to the top of the file.
Please refere to [working with frontmatter](/howtos/editors/frontmatter/) if you're not sure how to use it.
The following fields need to be filled in:
| Name | Description |
| ----:| ----------- |
| `date` | **Must** be in format `YYYY-MM-DD` |
| `title` | Title of the blog post |
| `linktitle` | If the title is very long, you can specify an alternative title for use in menus, breadcrumbs, and so on. This field is optional. |
| `img` | Filename of the main image. Must be placed in the folder of the showcase |
| `caption` | The caption that will go below the image |
| `author` | FreeSewing username of the author |
Below is an example:
```md
---
date: 2020-09-09
title: FreeSewing 2.9 brings our Teagan T-shirt pattern
linktitle: "Our latest pattern is Teagan, a fitted T-shirt"
img: teagan2.jpg
caption: "Photo by Alex Andrews from Pexels"
author: joost
---
```
Add the frontmatter to the top of the `en.md` file.

23
markdown/dev/editors/howtos/blogpost/add-images/en.md
View file

@ -1,23 +0,0 @@
---
title: Add images to the folder
order: 30
---
Add the images you want to use to the folder. Keep the following guidelines in mind:
- The main blog picture should be a landscape image
- The best resolution for the main image is 2000x1348 pixels
- None of the images should be larger than 2000px on their longest side
- Use lowercase for all filenames
<Note>
##### Please think twice before dropping a 7Mb image.
Git never forgets. So if you drop a couple of 7Mb images into our repo,
they will be there forever, making cloning the repo very slow.
So please resize your images before you commit your changes.
</Note>

14
markdown/dev/editors/howtos/blogpost/create-file/en.md
View file

@ -1,14 +0,0 @@
---
title: Create a new file for the blog post
order: 20
---
In the folder you just created, create a new empty file, and name it `en.md`.
<Note>
While we support translation, we do not support adding original content in
any language other than English. This is why the file **must** be named
`en.md` and be written in English.
</Note>

18
markdown/dev/editors/howtos/blogpost/create-folder/en.md
View file

@ -1,18 +0,0 @@
---
title: Create a new folder for the blog post
order: 10
---
Our [markdown repository](https://github.com/freesewing/markdown/) holds all content
for both freesewing.org and freesewing.dev.
The content for blog posts on freesewing.org is in the `org/blog` folder.
You'll find a bunch of directories here for all the existing blog posts.
Create a new one keeping in mind that this will determine the URL under which the post
is available. So:
- No spaces
- No uppercase
- Stick to `a-z` and `-` to be safe

12
markdown/dev/editors/howtos/blogpost/en.md
View file

@ -1,15 +1,11 @@
---
title: Adding a blog post on freesewing.org
title: Adding a blog post
for: editors
---
These are the steps required to add a new [blog post](https://freesewing.org/showcase/) to the website:
Blog posts have been migrated to [Strapi](https://strapi.io/), a headless CMS system.
<ReadMore list />
Our strapi instance can be accessed at [posts.freesewing.org](https://posts.freesewing.org/).
- Create a new folder in the `org/blog` directory of [our markdown repository](https://github.com/freesewing/markdown/)
- Add an `en.md` markdown file to this folder
- Add one of more images to the folder
- Add the frontmatter to the file
- Add the body of the file
If you don't have a Strapi account (yet), [reach out to us on Discord](https://discord.freesewing.org).

12
markdown/dev/editors/howtos/showcase/add-body/en.md
View file

@ -1,12 +0,0 @@
---
title: Add the body of the showcase post
order: 50
---
Below the frontmatter, you can write the body of your showcase post, [using markdown](/editors/markdown/).
<Tip>
You can look at [one of the many showcases](https://github.com/freesewing/markdown/tree/develop/org/showcase) for examples.
</Tip>

33
markdown/dev/editors/howtos/showcase/add-frontmatter/en.md
View file

@ -1,33 +0,0 @@
---
title: Add the frontmatter
order: 40
---
Frontmatter is metadata that we add to the top of the file.
Please refere to [working with frontmatter](/howtos/editors/frontmatter/) is you're not sure how to use it.
The following fields need to be filled in:
| Name | Description |
| ----:| ----------- |
| `date` | **Must** be in format `YYYY-MM-DD` |
| `title` | Title of the showcase |
| `img` | Filename of the main image. Must be placed in the folder of the showcase |
| `caption` | The caption that will go below the image |
| `patterns` | An array of designs/patterns that are being showcased. Lowercase only |
| `author` | FreeSewing username of the author |
Below is an example:
```md
---
date: 2018-09-29
title: Yoga Outfit by Paul
img: showcase.jpg
caption: "Aaron and Bruce yoga set with stripes by Paul (up-side-down)"
patterns: [aaron,bruce]
author: Tiger751023
---
```
Add the frontmatter to the top of the `en.md` file.

23
markdown/dev/editors/howtos/showcase/add-images/en.md
View file

@ -1,23 +0,0 @@
---
title: Add images to the folder
order: 30
---
Add the images you want to use to the folder. Keep the following guidelines in mind:
- The main showcase picture should, if possible, be a landscape image
- The best resolution for the main image is 2000x1348 pixels
- None of the images should be larger than 2000px on their longest side
- Use lowercase for all filenames
<Note>
##### Please think twice before dropping a 7Mb image.
Git never forgets. So if you drop a couple of 7Mb images into our repo,
they will be there forever, making cloning the repo very slow.
So please resize your images before you commit your changes.
</Note>

14
markdown/dev/editors/howtos/showcase/create-file/en.md
View file

@ -1,14 +0,0 @@
---
title: Create a new file for the showcase post
order: 20
---
In the folder you just created, create a new empty file, and name it `en.md`.
<Note>
While we support translation, we do not support adding original content in
any language other than English. This is why the file **must** be named
`en.md` and be written in English.
</Note>

18
markdown/dev/editors/howtos/showcase/create-folder/en.md
View file

@ -1,18 +0,0 @@
---
title: Create a new folder for the showcase post
order: 10
---
Our [markdown repository](https://github.com/freesewing/markdown/) holds all content
for both freesewing.org and freesewing.dev.
The content for showcases on freesewing.org is in the `org/showcase` folder.
You'll find a bunch of directories here for all the existing showcases.
Create a new one keeping in mind that this will determine the URL under which the showcase
is available. So:
- No spaces
- No uppercase
- Stick to `a-z` and `-` to be safe

78
markdown/dev/editors/howtos/showcase/en.md
View file

@ -3,80 +3,8 @@ title: Adding a showcase on freesewing.org
for: editors
---
These are the steps required to add a new [showcase](https://freesewing.org/showcase/) to the website:
Showcase posts have been migrated to [Strapi](https://strapi.io/), a headless CMS system.
- Create a new folder in the `org/showcase` directory of [our markdown repository](https://github.com/freesewing/markdown/)
- Add an `en.md` markdown file to this folder
- Add one of more images to the folder
- Add the frontmatter to the file
- Add the body of the file
Our strapi instance can be accessed at [posts.freesewing.org](https://posts.freesewing.org/).
Let's look at each step in detail:
## Create a new folder for the showcase
Our [markdown repository](https://github.com/freesewing/markdown/) holds all content
for both freesewing.org and freesewing.dev.
The content for showcases on freesewing.org is in the `org/showcase` folder.
You'll find a bunch of directories here for all the existing showcases.
Create a new one keeping in mind that this will determine the URL under which the showcase
is available. So:
- No spaces
- No uppercase
- Stick to `a-z` and `-` to be safe
## Add an `en.md` file to the folder
Create an empty file in this folder and name it `en.md`.
## Add one of more images to the folder
Add the images you want to use to the folder.
<Note>We prefer if you use lowercase for all filenames</Note>
## Add the frontmatter
Frontmatter is metadata that we add to the top of the file.
Please refere to [working with frontmatter](/editors/frontmatter) is you're not sure how to use it.
The following fields need to be filled in:
| Name | Description |
| ---- | ----------- |
| `date` | Must be in format `YYYY-MM-DD` |
| `title` | Title of the showcase |
| `img` | Filename of the main image. Must be placed in the folder of the showcase |
| `caption` | The caption that will go below the image |
| `patterns` | An array of designs/patterns that are being showcased. Lowercase only |
| `author` | FreeSewing username of the author |
Below is an example:
```md
---
date: 2018-09-29
title: Yoga Outfit by Paul
img: showcase.jpg
caption: "Aaron and Bruce yoga set with stripes by Paul (up-side-down)"
patterns: [aaron,bruce]
author: Tiger751023
---
```
Add the frontmatter to the top of the `en.md` file.
## Add the body
Below the frontmatter, you can write the body of your post, [using markdown](/editors/markdown/).
<Tip>
You can look at [one of the many showcases](https://github.com/freesewing/markdown/tree/develop/org/showcase) for examples.
</Tip>
If you don't have a Strapi account (yet), [reach out to us on Discord](https://discord.freesewing.org).

15
markdown/dev/translators/crowdin/en.md
View file

@ -1,15 +0,0 @@
---
title: Crowdin
---
We use [crowdin](https://crowdin.com/) to manage all translations for FreeSewing.
It's an online platform that makes translation a breeze.
There's a good deal of documentation on Crowdin online, so we won't try to replicate that here.
To get started, you will need to be invited as a translator. No need to worry,
simply [let us know you'd like to help out](https://discord.freesewing.org/) and we'll add you.
We have two projects on Crowdin that each handle a specific type of content:
<ReadMore list />

15
markdown/dev/translators/crowdin/freesewing/en.md
View file

@ -1,15 +0,0 @@
---
title: freesewing
---
This Crowdin project holds all the *strings* that are used to make the FreeSewing software multilingual.
Crowdin makes translations of such strings very easy.
If you provide the translation, Crowdin will make sure your changes make it back
into our repository, where they will be picked up and merged by one of the development people.
Here's what you need to know to get started:
- Crowdin link: https://crowdin.com/project/freesewing
- Request an invite: https://discord.freesewing.org/

35
markdown/dev/translators/crowdin/freesewing/syntax/en.md
View file

@ -1,35 +0,0 @@
---
title: Syntax
---
Most strings are just text, but sometimes you'll find a little markup sprinkled in.
#### HTML formatting
When you encounter HTML tags, simply translate around them. For example:
```yaml
<b>No</b>, never.
```
looks like this in Spanish:
```yaml
<b>No</b>, nunca.
```
#### Placeholders
When you encounter a `{key}` between curly braces, leave it as-is.
These will be filled in later with the correct value. For example:
```yaml
{field} saved
```
looks like this in Spanish
```yaml
{field} guardado
```

23
markdown/dev/translators/crowdin/markdown/en.md
View file

@ -1,23 +0,0 @@
---
title: Markdown
---
This Crowdin project holds all our *markdown content*.
Crowdin makes translations of content very easy by breaking it apart into sentences and paragraphs.
This may seem weird at first, but it actually has a number of benefits:
- You never have to tackle an enourmous page of documentation. Whenever you have a few
minutes to spare, you can just jump in, and translate a few sentences. This makes it much
simpler to collaborate with others.
- When (part) of the original (English) content is changed, Crowdin will detect that and let you know exactly what sentences need to be updated.
- It's easier to keep track of how much has been done/remains to be done
- Content is more consistent across languages
Once you provide the translation, Crowdin will make sure your changes make it back
into our repository, where they will be picked up and merged by one of the development people.
Here's what you need to know to get started:
- Crowdin link: https://crowdin.com/project/fs-markdown
- Request an invite: https://discord.freesewing.org/

11
markdown/dev/translators/crowdin/markdown/syntax/en.md
View file

@ -1,11 +0,0 @@
---
title: Syntax
---
# Syntax
Content will contain MarkDown syntax. MarkDown is a straight-forward way to format text
to turn it into HTML. You’ll be familiar with it in no time.
Our [guide on Markdown](/editors/markdown/) covers all you need to know.
If you have any questions, [we're here to help](https://discord.freesewing.org/).

5
markdown/dev/translators/empty/en.md Normal file
View file

@ -0,0 +1,5 @@
---
title: " "
---
This page was intentionally left blank.

77
markdown/dev/translators/en.md
View file

@ -3,12 +3,79 @@ title: For translators
order: 1140
---
Freesewing is proudly multilingual, and for this we depend on translators to help us.
Freesewing is proudly multilingual. We currently support 5 languges:
We use [crowdin](https://crowdin.com/) to manage translations for FreeSewing,
and currently support 5 languages.
We currently support the following five languages:
Find out more with the links below:
- **en** : English
- **de** : German
- **es** : Spanish
- **fr** : French
- **nl** : Dutch
<ReadMore list />
<Note>
If you'd like to start working on a new language, that's great, but a bit
beyond the scope of this documentation. So in that case,
please [come and talk to us on Discord](https://discord.freesewing.org).
</Note>
For content hosted on [strapi](/editors/content/#strapi), translation is available within Strapi as different language versions of the same post.
For markdown content and strings, we use [crowdin](https://crowdin.com/) to manage translations.
It's an online platform that makes translation a breeze.
There's a good deal of documentation on Crowdin online, so we won't try to replicate that here.
You can access the Crowdin project at: [translate.freesewing.org](https://translate.freesewing.org).
To get started, you will need to be invited as a translator. No need to worry,
simply [let us know you'd like to help out](https://discord.freesewing.org/) and we'll add you.
<Tip>
##### English as origin langauge, and differences between Crowding and Strapi
Our content comes in two flavors:
- Strings and markdown content **on Crowdin**. Here, English is the **origin language** and
translations are kept close to the origin.
- Blog posts and showcases **on strapi**. Here, there is no origin langauge. People can write
blog posts in any language, or translate more freely to adapt the content to a different audience.
</Tip>
## Syntax
Most strings are just text, but sometimes you'll find a little markup sprinkled in.
#### HTML formatting
When you encounter HTML tags, simply translate around them. For example:
```yaml
<b>No</b>, never.
```
looks like this in Spanish:
```yaml
<b>No</b>, nunca.
```
#### Placeholders
When you encounter a `{key}` between curly braces, leave it as-is.
These will be filled in later with the correct value. For example:
```yaml
{field} saved
```
looks like this in Spanish
```yaml
{field} guardado
```

19
markdown/dev/translators/languages/en.md
View file

@ -1,19 +0,0 @@
---
title: Languages
---
English is our origin language. Which means that everything is written in English
and then translated from English into other languages.
We currently support the following five languages:
- **en** : English (our origin language)
- **de** : German
- **es** : Spanish
- **fr** : French
- **nl** : Dutch
If you'd like to start working on a new language, that's great, but a bit
beyond the scope of this documentation. So in that case,
please [come and talk to us on Discord](https://discord.freesewing.org).