Update community resources for migration guides #11376
Conversation
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Lunaria Status Overview🌕 This pull request will trigger status changes. Learn moreBy default, every PR changing files present in the Lunaria configuration's You can change this by adding one of the keywords present in the Tracked Files
Warnings reference
|
There was a problem hiding this comment.
This looks great! And I think this wasn't a funny task so... 🙌🏽
I only left a few suggestions: some reorganization based on Firefox adaptive view, and two more generic comments (not necessarily an issue, but just to share in case you have better ideas than me 😄 ).
I'm not sure what we can do regarding the "strategic ordering of entries". I guess we could define the most recent links at the top to make them more visible but:
- This could conflict with space balancing
- If someone adds a new link, I guess the most logical position in this case is at the bottom so... this is not better than no ordering I guess.
| - Add your own! | ||
| <CardGrid> | ||
|
|
||
| <LinkCard title="Speeding up documentation by 10 times" href="https://habr.com/ru/articles/880220/"/> |
There was a problem hiding this comment.
Nothing wrong here but I'm wondering what we should do with links in another language... Here, without checking if a locale is present in the URL, the user might expect a link in English since the title is translated while the link is in Russian. So it could be confusing.
Here are some ideas:
- We could add an
hreflang="ru"attribute which I think could help with accessibility... but there is no visual clue. So, not ideal. - We could just add a visual clue (e.g.
(ru)at the end of the title). I think this is common enough to be understandable. Not sure if this makes sense with screen readers without thehreflangthough. - We could use the first two points together. And this could even be a custom
LinkCardcomponent that wraps the Starlight one and that accepts an optionallocaleto both set thehreflangand concatenate the title with a visual clue (e.g.(ru)... not sure how it should work with RTL languages though). However, this could be confusing for writers to have the choice between two similar components.
I'm not sure what else we could do here at the moment. So it was mainly to highlight the possible confusion! 😅
There was a problem hiding this comment.
What I usually do in the blog posts is use an English translation of the title, then e.g. (Russian) after. I thought about doing that here, but also, when I click on posts that are in other languages, my browser just translates. So, I'm not sure it entirely matters the language of the original? Yes, it can be a good "warning" but I'm not sure how necessary it is with browsers mostly able to translate for you and, while sure, it's machine translation, you can generally still "read" the content to get an idea. Open to opinions on this!
There was a problem hiding this comment.
Honestly I don't have a strong opinion on this I just wanted to point this out just in case because this is something we tend to do in the French translation at least with community resources (title + (en)). So I'm used to look at this. I think that's also something that is done on the German translation (at least I think trueberryless mention that on Discord).
I thought we had links in Spanish, I wanted to check what was done but impossible... it may be from the removed community recipes. Or the title is translated without a language indication and I only noticed that while translating in French.
But, good point, I hadn't thought of writing the whole language name as an alternative! Seems easier than a custom component. 😆 Yet I had already seen that in the What's new in Astro posts. Perhaps this is because they are regular lists instead of cards lists so I didn't make the connection. 😅
I don't know if there are any statistics regarding the use of browser machine translation but this is indeed something to consider! I am probably the exception that proves the rule... so I haven't thought of this neither!
I rarely use it and certainly not in an automatic way (I prefer to opt-in on a case per case basis, and to be honest this remains pretty rare because I rarely read things in other languages than the ones I know). And I like to know in advance where I'm going to land. But, just looking at the URL is fine for me. Not sure what others do.
So we can probably ignore this. It could land in the box "we thought about it but we didn't see the point" (NWTWWHB? funny enough while checking if I spell it correctly it's your website that appears first 😄 ).
| @@ -604,5 +604,5 @@ description="Why and how I migrated this website from Gatsby to Astro."/> | |||
| </CardGrid> | |||
|
|
|||
| :::note[Have a resource to share?] | |||
| If you found (or made!) a helpful video or blog post about converting a Gatsby site to Astro, [edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx) and add it here! | |||
There was a problem hiding this comment.
Although I understand that this link is not useful in the English version since we already have Edit this page at the bottom, I think this can be useful for translations. Because we want these changes to be made to the English version, not the translation.
For example, in French this link uses the English version while the link for Modifier cette page at the bottom uses the French version.
But maybe I'm overthinking here and it's just fine to remove it. 😅
There was a problem hiding this comment.
Ah, good point! I had removed the link because of the language implications, and so as not to need to duplicate the logic of the "edit this page" link feature. But you're right, it's not actually edit THIS page in the translations then... it really should always be the English page... That gets a little clunky to say though, "Edit this (the page the link is taking you to, not the page you're actually on) page" 😅
What we could do is introduce hard-coded links pointing to the English file and maybe the linked text is something like [add it to this list](/en/...)?
There was a problem hiding this comment.
Sounds like a good idea!
And yeah, while linking the French page I was saying to myself the translation is wrong we should probably use modifiez la version anglaise de cette page but that wasn't the point. 😅
There was a problem hiding this comment.
Sorry for causing so much trouble, but well done! 💜 (at first glance, I'll review the PR tomorrow if no one does it first!)
src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx
Outdated
Show resolved
Hide resolved
Co-authored-by: Armand Philippot <git@armand.philippot.eu>
src/content/docs/en/guides/migrate-to-astro/from-create-react-app.mdx
Outdated
Show resolved
Hide resolved
src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx
Outdated
Show resolved
Hide resolved
sarah11918
added
add new content
Description (required)
Updates the "Migrate to Astro from..." guides in the Community resources section to:
<LinkCard>s (like the Gatsby one currently does) instead of Markdown linksAlso updates a few CMS/deploy guides when similar relevant community resources were found.
DRAFT:
This is a draft because I haven't yet previewed, nor thought about strategic ordering of entries. Just got all content added and committed quickly because I was having editor issues.
TO REVIEW:
Visit every Migration guide and check the bottom of the page (Community Resources section) for anything amiss! Link cards can be reordered if you see a better ordering!