Skip to content

Commit f667c8a

Browse files
alvarosabualvarosabu
committed
docs: enable multi language
1 parent 91e047a commit f667c8a

26 files changed

+2739
-0
lines changed

‎docs/.vitepress/config/en.ts

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
2+
3+
export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
4+
themeConfig: {
5+
editLink: {
6+
pattern: 'https://github.com/tresjs/tres/edit/main/packages/docs/:path',
7+
text: 'Suggest changes to this page',
8+
},
9+
sidebar: [
10+
{
11+
text: 'Guide',
12+
items: [
13+
// This shows `/guide/index.md` page.
14+
{ text: 'Introduction', link: '/guide/' },
15+
{ text: 'Getting Started', link: '/guide/getting-started' },
16+
{ text: 'Your first Scene', link: '/guide/your-first-scene' },
17+
{ text: 'Nuxt', link: '/guide/nuxt' },
18+
{ text: 'Troubleshooting', link: '/guide/troubleshooting' },
19+
{ text: 'Migrate from v1', link: '/guide/migration-guide' },
20+
],
21+
},
22+
{
23+
text: 'API',
24+
items: [
25+
{ text: 'TresCanvas', link: '/api/tres-canvas' },
26+
{
27+
text: 'Instances, arguments and props',
28+
link: '/api/instances-arguments-and-props',
29+
},
30+
{
31+
text: 'Composables',
32+
link: '/api/composables',
33+
},
34+
{
35+
text: 'Events',
36+
link: '/api/events',
37+
},
38+
],
39+
},
40+
41+
{
42+
text: 'Advanced',
43+
44+
items: [
45+
{ text: 'Extending', link: '/advanced/extending' },
46+
{ text: 'primitive', link: '/advanced/primitive' },
47+
{
48+
text: 'Caveats',
49+
link: '/advanced/caveats',
50+
},
51+
],
52+
},
53+
{
54+
text: 'Debug',
55+
items: [
56+
{ text: 'Devtools', link: '/debug/devtools' },
57+
],
58+
},
59+
{
60+
text: 'Examples',
61+
collapsed: true,
62+
items: [
63+
{ text: 'Orbit Controls', link: '/examples/orbit-controls' },
64+
{ text: 'Basic Animations', link: '/examples/basic-animations' },
65+
{ text: 'Groups', link: '/examples/groups' },
66+
{ text: 'Load Textures', link: '/examples/load-textures' },
67+
{ text: 'Load Models', link: '/examples/load-models' },
68+
{ text: 'Load Text', link: '/examples/text-3d' },
69+
{ text: 'Lights & Shadows', link: '/examples/lights-shadows' },
70+
{ text: 'Shaders', link: '/examples/shaders' },
71+
],
72+
},
73+
{
74+
text: 'Directives',
75+
collapsed: true,
76+
items: [
77+
{ text: 'v-log', link: '/directives/v-log' },
78+
{ text: 'v-light-helper', link: '/directives/v-light-helper' },
79+
{ text: 'v-always-look-at', link: '/directives/v-always-look-at' },
80+
{ text: 'v-distance-to', link: '/directives/v-distance-to' },
81+
],
82+
},
83+
{
84+
text: 'Ecosystem',
85+
items: [
86+
{
87+
text: 'Cientos 💛',
88+
link: 'https://cientos.tresjs.org/',
89+
},
90+
{
91+
text: 'Nuxt module',
92+
link: 'https://github.com/Tresjs/nuxt',
93+
},
94+
{
95+
text: 'TresLeches 🍰',
96+
link: 'https://tresleches.tresjs.org/',
97+
},
98+
{
99+
text: 'Post-processing (Soon)',
100+
},
101+
],
102+
},
103+
],
104+
nav: [
105+
{ text: 'Guide', link: '/guide/' },
106+
{ text: 'API', link: '/api/tres-canvas' },
107+
/* { text: 'API', link: '/api/' },
108+
{ text: 'Config', link: '/config/' }, */
109+
{ text: 'Resources',
110+
items: [
111+
{ text: 'Team', link: '/team' },
112+
{ text: 'Releases', link: 'https://github.com/Tresjs/tres/releases' },
113+
{
114+
text: 'Playground',
115+
link: 'https://playground.tresjs.org/',
116+
},
117+
{
118+
text: 'Github',
119+
link: 'https://github.com/Tresjs/tres/',
120+
},
121+
{
122+
text: 'Issues',
123+
link: 'https://github.com/Tresjs/tres/issues',
124+
},
125+
{
126+
text: 'Ecosystem',
127+
items: [
128+
{
129+
text: 'Cientos 💛',
130+
link: 'https://cientos.tresjs.org/',
131+
},
132+
{
133+
text: 'Nuxt module',
134+
link: 'https://github.com/Tresjs/nuxt',
135+
},
136+
{
137+
text: 'TresLeches 🍰',
138+
link: 'https://tresleches.tresjs.org/',
139+
},
140+
],
141+
},
142+
],
143+
},
144+
],
145+
},
146+
}

‎docs/.vitepress/config/index.ts

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
import { defineConfig } from 'vitepress'
2+
import { enConfig } from './en'
3+
import { sharedConfig } from './shared'
4+
5+
/* import { zhConfig } from './zh' */
6+
7+
export default defineConfig({
8+
...sharedConfig,
9+
10+
locales: {
11+
root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
12+
es: { label: 'Español', lang: 'es-ES', link: '/es/', ...enConfig },
13+
/* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
14+
},
15+
})

‎docs/.vitepress/config/shared.ts

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
import { defineConfig } from 'vitepress'
2+
import { resolve } from 'pathe'
3+
4+
export const sharedConfig = defineConfig({
5+
title: 'TresJS',
6+
description: 'Declarative ThreeJS using Vue Components',
7+
head: [
8+
['link', { rel: 'icon', type: 'image/svg', href: '/favicon.svg' }],
9+
['meta', { name: 'theme-color', content: '#82DBC5' }],
10+
['meta', { name: 'twitter:card', content: 'summary_large_image' }],
11+
['meta', { name: 'twitter:site', content: '@tresjs_dev' }],
12+
['meta', { name: 'twitter:creator', content: '@tresjs_dev' }],
13+
['meta', { property: 'og:type', content: 'website' }],
14+
['meta', { property: 'og:site_name', content: 'TresJS' }],
15+
[
16+
'meta',
17+
{
18+
property: 'og:image',
19+
content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
20+
},
21+
],
22+
[
23+
'meta',
24+
{
25+
property: 'twitter:image',
26+
content: 'https://repository-images.githubusercontent.com/571314349/10996566-7f70-473b-a8e5-4e56fc0ca850',
27+
},
28+
],
29+
['script', { defer: 'true', 'data-domain': 'tresjs.org', src: 'https://plausible.io/js/script.js' }],
30+
],
31+
themeConfig: {
32+
logo: '/logo.svg',
33+
socialLinks: [
34+
{ icon: 'github', link: 'https://github.com/tresjs/tres' },
35+
{ icon: 'x', link: 'https://twitter.com/tresjs_dev' },
36+
{ icon: 'discord', link: 'https://discord.gg/UCr96AQmWn' },
37+
],
38+
},
39+
vite: {
40+
optimizeDeps: {
41+
exclude: ['vitepress'],
42+
include: ['three'],
43+
},
44+
server: {
45+
hmr: {
46+
overlay: false,
47+
},
48+
},
49+
resolve: {
50+
alias: {
51+
'@tresjs/core': resolve(__dirname, '../../../dist/tres.js'),
52+
},
53+
dedupe: ['@tresjs/cientos', 'three'],
54+
},
55+
},
56+
vue: {
57+
template: {
58+
compilerOptions: {
59+
isCustomElement: tag => tag.startsWith('Tres') && tag !== 'TresCanvas',
60+
},
61+
},
62+
},
63+
})

‎docs/es/advanced/caveats.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Avisos 😱
2+
3+
Nuestro objetivo es proporcionar una forma sencilla de utilizar ThreeJS en VueJS con la mejor experiencia de desarrollo posible. Sin embargo, hay algunas advertencias de las que debes ser consciente.
4+
5+
## ~~HMR y ThreeJS~~
6+
7+
:::info
8+
9+
Esto se ha solucionado en **TresJS** v1.7.0 🎉. Ahora puedes utilizar HMR sin tener que recargar la página 🥹.
10+
11+
:::
12+
13+
La sustitución de módulos en caliente (HMR) es una característica que te permite actualizar tu código sin recargar la página. Esta es una gran característica que hace que el desarrollo sea mucho más rápido. **TresJS** utiliza [Vite](https://vitejs.dev/). Sin embargo, es realmente complicado hacer que funcione correctamente con ThreeJS.
14+
15+
¿Por qué? Porque Tres construye la escena de forma declarativa. Esto significa que crea la instancia y la añade a la escena cuando se monta el componente. La complejidad radica en saber cuándo quitar la instancia de la escena y cuándo añadirla de nuevo.
16+
17+
Aunque se ha implementado un flujo de eliminación mínimo, no es perfecto. Esto significa que a veces tendrás que recargar la página para ver los cambios correctamente, especialmente cuando estás haciendo referencia a instancias utilizando [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)
18+
19+
```vue
20+
<script setup lang="ts">
21+
const boxRef: Ref<TresInstance | null> = ref(null)
22+
23+
onLoop(({ _delta, elapsed }) => {
24+
if (boxRef.value) {
25+
boxRef.value.rotation.y += 0.01
26+
boxRef.value.rotation.z = elapsed * 0.2
27+
}
28+
})
29+
</script>
30+
31+
<template>
32+
<TresMesh
33+
ref="boxRef"
34+
:scale="1"
35+
cast-shadow
36+
>
37+
<TresBoxGeometry :args="[1, 1, 1]" />
38+
<TresMeshStandardMaterial color="teal" />
39+
</TresMesh>
40+
</template>
41+
```
42+
43+
Si realizas un cambio en el `color` del componente `TresMeshStandardMaterial`, verás que el cambio se aplica pero la rotación ya no funciona. Esto se debe a que la instancia se elimina y se crea de nuevo.
44+
45+
:::tip
46+
Entonces, como **regla general**, debes recargar la página cuando no veas los cambios que has realizado.
47+
:::
48+
49+
Dicho esto, estamos trabajando en una mejor solución para esto 😁. Si tienes alguna idea de cómo resolverlo, por favor avísanos.
50+
51+
Puedes seguir la discusión en [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23)
52+
53+
## Reactividad
54+
55+
Todos amamos la reactividad 💚. Es una de las características más poderosas de VueJS. Sin embargo, debemos tener cuidado al usar ThreeJS.
56+
57+
La reactividad de Vue se basa en [Proxy](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Esto permite que Vue 3 rastree automáticamente los cambios en los objetos de datos y actualice los elementos DOM correspondientes cada vez que los datos cambien.
58+
59+
Dado que estamos renderizando una escena y actualizándola en cada fotograma (60FPS), eso significa que estamos actualizando la escena 60 veces por segundo. Si el objeto a actualizar es reactivo, Vue intentará actualizar ese objeto tantas veces. Esto no es una buena idea 😅 y será perjudicial para el rendimiento.
60+
61+
Aquí tienes una prueba de rendimiento de la diferencia entre usar un objeto Proxy y un objeto plano.
62+
63+
<figure>
64+
<img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
65+
<figcaption>Fig.1 - Ejecuciones por segundo Objeto Plano vs Proxy. </figcaption>
66+
</figure>
67+
68+
Fuente: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)
69+
70+
Si te ves obligado a usar reactividad, utiliza [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)
71+
72+
A diferencia de `ref()`, el valor interno de un shallow ref se almacena y se expone tal cual, y no se hace reactividad profunda. Solo el acceso a `.value` es reactivo. Fuente [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref)
73+
74+
### Ejemplo
75+
76+
❌ Incorrecto
77+
78+
```vue
79+
<script setup lang="ts">
80+
const position = reactive({ x: 0, y: 0, z: 0 })
81+
82+
onLoop(({ _delta, elapsed }) => {
83+
position.x = Math.sin(elapsed * 0.1) * 3
84+
})
85+
</script>
86+
87+
<template>
88+
<TresMesh
89+
:position="position"
90+
cast-shadow
91+
>
92+
<TresBoxGeometry :args="[1, 1, 1]" />
93+
<TresMeshStandardMaterial color="teal" />
94+
</TresMesh>
95+
</template>
96+
```
97+
98+
✅ Correcto
99+
100+
```vue
101+
<script setup lang="ts">
102+
const position = { x: 0, y: 0, z: 0 }
103+
const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)
104+
105+
onLoop(({ _delta, elapsed }) => {
106+
boxRef.value.position.x = Math.sin(elapsed * 0.1) * 3
107+
})
108+
</script>
109+
110+
<template>
111+
<TresMesh
112+
ref="boxRef"
113+
:position="position"
114+
cast-shadow
115+
>
116+
<TresBoxGeometry :args="[1, 1, 1]" />
117+
<TresMeshStandardMaterial color="teal" />
118+
</TresMesh>
119+
</template>
120+
```

‎docs/es/advanced/extending.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Extender 🔌
2+
3+
Tres ofrece la funcionalidad básica, pero es fácil agregar elementos de terceros y extenderlos en su catálogo interno.
4+
5+
La mayoría de las experiencias en 3D utilizan `OrbitControls`, que no forma parte de la biblioteca principal. Puedes agregarlo a tu proyecto importándolo desde el módulo `three/addons/controls/OrbitControls`.
6+
7+
```js
8+
import { OrbitControls } from 'three/addons/controls/OrbitControls'
9+
```
10+
11+
## Extender un elemento dinámicamente
12+
13+
También puedes agregarlo dinámicamente en tus componentes:
14+
15+
```vue {2,3,4,7,13,15}
16+
<script setup lang="ts">
17+
import { extend } from '@tresjs/core'
18+
import { OrbitControls } from 'three/addons/controls/OrbitControls'
19+
import { TextGeometry } from 'three/addons/geometries/TextGeometry'
20+
21+
// Añadimos OrbitControls al catalogo interno
22+
extend({ TextGeometry, OrbitControls })
23+
</script>
24+
25+
<template>
26+
<TresCanvas
27+
shadows
28+
alpha
29+
>
30+
<TresPerspectiveCamera :position="[5, 5, 5]" />
31+
<TresOrbitControls
32+
v-if="state.renderer"
33+
:args="[state.camera, state.renderer?.domElement]"
34+
/>
35+
<TresMesh>
36+
<TresTextGeometry
37+
:args="['TresJS', { font, ...fontOptions }]"
38+
center
39+
/>
40+
<TresMeshMatcapMaterial :matcap="matcapTexture" />
41+
</TresMesh>
42+
</TresCanvas>
43+
</template>
44+
```

0 commit comments

Comments
 (0)